Beranda>Terkait pemrograman>Kode sumber lainnya
Unduh

Angular ng-select - Ringan semuanya dalam satu UI Select, Multiselect, dan Autocomplete

Lihat halaman Demo.

Versi

sudut ng-pilih
>=19.0.0 <20.0.0 v14.x
>=18.0.0 <19.0.0 v13.x
>=17.0.0 <18.0.0 v12.x
>=16.0.0 <17.0.0 v11.x
>=15.0.0 <16.0.0 v10.x
>=14.0.0 <15.0.0 v9.x
>=13.0.0 <14.0.0 v8.x
>=12.0.0 <13.0.0 v7.x
>=11.0.0 <12.0.0 v6.x
>=10.0.0 <11.0.0 v5.x
>=9.0.0 <10.0.0 v4.x
>=8.0.0 <9.0.0 v3.x
>=6.0.0 <8.0.0 v2.x
v5.xx v1.x

Dukungan Peramban

ng-select mendukung semua browser yang didukung oleh Angular. Untuk daftar saat ini, lihat https://angular.io/guide/browser-support#browser-support. Ini mencakup versi spesifik berikut: 

 Chrome	2 most recent versions
Firefox	latest and extended support release (ESR)
Edge	2 most recent major versions
Safari	2 most recent major versions
iOS	2 most recent major versions
Android	2 most recent major versions

Daftar isi

  • Fitur
  • Memulai
  • API
  • Ubah deteksi
  • Gaya khusus
    • Status validasi
  • Berkontribusi
  • Perkembangan
  • Inspirasi

Fitur

  • Pengikatan khusus pada properti atau objek
  • Opsi khusus, label, templat header dan footer
  • Dukungan Gulir Virtual dengan kumpulan data besar (>5000 item).
  • Gulir tanpa batas
  • Navigasi papan ketik
  • Pilih banyak
  • Pelengkapan otomatis yang fleksibel dengan pemfilteran klien/server
  • Pencarian khusus
  • Tag khusus
  • Tambahkan ke
  • Item kelompok
  • Peristiwa keluaran
  • Aksesibilitas
  • Cakupan pengujian fungsionalitas dasar yang baik
  • Tema

Peringatan

Perpustakaan sedang dalam pengembangan aktif dan mungkin ada perubahan yang dapat menyebabkan gangguan API untuk versi utama berikutnya setelah 1.0.0.

Memulai

Langkah 1: Instal ng-select :

NPM 

npm install --save @ng-select/ng-select

BENANG 

yarn add @ng-select/ng-select

Langkah 2:

Mandiri: Impor NgSelectComponent dan arahan lain yang diperlukan secara langsung: 

 import { NgLabelTemplateDirective , NgOptionTemplateDirective , NgSelectComponent } from '@ng-select/ng-select' ;
import { FormsModule } from '@angular/forms' ;

@ Component ( {
  selector : 'example' ,
  standalone : true ,
  template : './example.component.html' ,
  styleUrl : './example.component.scss' ,
  imports : [
    NgLabelTemplateDirective ,
    NgOptionTemplateDirective ,
    NgSelectComponent ,
  ] ,
} )
export class ExampleComponent { }

NgModule: Impor modul NgSelectModule dan Angular FormsModule: 

 import { NgSelectModule } from '@ng-select/ng-select' ;
import { FormsModule } from '@angular/forms' ;

@ NgModule ( {
  declarations : [ AppComponent ] ,
  imports : [ NgSelectModule , FormsModule ] ,
  bootstrap : [ AppComponent ]
} )
export class AppModule { }

Langkah 3: Sertakan tema:

Untuk memungkinkan penyesuaian dan pemberian tema, bundel ng-select hanya menyertakan gaya umum yang diperlukan untuk tata letak dan pemosisian yang benar. Untuk mendapatkan tampilan kontrol penuh, sertakan salah satu tema dalam aplikasi Anda. Jika Anda menggunakan Angular CLI, Anda dapat menambahkan ini ke styles.scss atau memasukkannya ke dalam .angular-cli.json (Angular v5 dan di bawahnya) atau angular.json (Angular v6 dan seterusnya). 

 @import " ~@ng-select/ng-select/themes/default.theme.css " ;
// ... or 
@import " ~@ng-select/ng-select/themes/material.theme.css " ;

Langkah 4 (Opsional): Konfigurasi

Anda juga dapat mengatur konfigurasi global dan pesan pelokalan dengan memasukkan layanan NgSelectConfig, biasanya di komponen root Anda, dan menyesuaikan nilai propertinya untuk memberikan nilai default. 

  constructor ( private config : NgSelectConfig ) {
      this . config . notFoundText = 'Custom not found' ;
      this . config . appendTo = 'body' ;
      // set the bindValue to global config when you use the same 
      // bindValue in most of the place. 
      // You can also override bindValue for the specified template 
      // by defining `bindValue` as property
      // Eg : <ng-select bindValue="some-new-value"></ng-select>
      this . config . bindValue = 'value' ;
  }

Penggunaan

Tentukan opsi dalam komponen konsumsi Anda: 

@ Component ( { ... } )
export class ExampleComponent {

    selectedCar : number ;

    cars = [
        { id : 1 , name : 'Volvo' } ,
        { id : 2 , name : 'Saab' } ,
        { id : 3 , name : 'Opel' } ,
        { id : 4 , name : 'Audi' } ,
    ] ;
}

Dalam template gunakan komponen ng-select dengan pilihan Anda 

 <!--Using ng-option and for loop-->
< ng-select [(ngModel)] =" selectedCar " >
    @for (car of cars; track car.id) {
        < ng-option [value] =" car.id " > {{car.name}} </ ng-option >
    }
</ ng-select >

<!--Using items input-->
< ng-select [items] =" cars " 
           bindLabel =" name " 
           bindValue =" id " 
           [(ngModel)] =" selectedCar " >
</ ng-select >

Untuk contoh lebih rinci lihat halaman Demo

SistemJS

Jika Anda menggunakan SystemJS, Anda juga harus menyesuaikan konfigurasi agar mengarah ke bundel UMD.

Dalam file konfigurasi systemjs Anda, map perlu memberi tahu System loader di mana mencari ng-select : 

map: {
  '@ng-select/ng-select' : 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js' ,
}

API

Masukan

Masukan Jenis Bawaan Diperlukan Keterangan
[tambahkanTag] boolean | ((term: string) => any | Promise<any>) false TIDAK Memungkinkan untuk membuat opsi khusus.
tambahkanTagTeks string Add item TIDAK Atur teks khusus saat menggunakan penandaan
penampilan string underline TIDAK Memungkinkan untuk memilih tampilan dropdown. Setel ke outline untuk menambahkan batas, bukan garis bawah (hanya berlaku untuk tema Material)
tambahkan Ke string batal TIDAK Tambahkan dropdown ke badan atau elemen lainnya menggunakan pemilih css. Untuk posisi yang benar, body harus memiliki position:relative
jumlah buffer string batal TIDAK Tambahkan dropdown ke badan atau elemen lainnya menggunakan pemilih css. Untuk posisi yang benar, body harus memiliki position:relative
mengikatNilai string - TIDAK Properti objek yang akan digunakan untuk model yang dipilih. Secara default mengikat seluruh objek.
mengikatLabel string label TIDAK Properti objek yang akan digunakan untuk label. label bawaan
[tutupPadaPilihan] boolean BENAR TIDAK Apakah akan menutup menu ketika suatu nilai dipilih
hapusSemuaTeks string Clear all TIDAK Atur teks khusus untuk menghapus semua judul ikon
[dapat dihapus] boolean true TIDAK Izinkan untuk menghapus nilai yang dipilih. Standarnya true
[clearOnBackspace] boolean true TIDAK Hapus nilai yang dipilih satu per satu saat mengklik backspace. Standarnya true
[bandingkanDengan] (a: any, b: any) => boolean (a, b) => a === b TIDAK Fungsi untuk membandingkan nilai opsi dengan nilai yang dipilih. Argumen pertama adalah nilai dari suatu opsi. Yang kedua adalah nilai dari pilihan (model). Boolean harus dikembalikan.
dropdownPosisi bottom | top | auto auto TIDAK Atur posisi dropdown pada posisi terbuka
[Placeholder tetap] boolean false TIDAK Atur placeholder terlihat bahkan ketika item dipilih
[grupOleh] string | Function batal TIDAK Izinkan untuk mengelompokkan item berdasarkan ekspresi kunci atau fungsi
[Nilai grup] (groupKey: string, children: any[]) => Object - TIDAK Ekspresi fungsi untuk memberikan nilai grup
[Grup yang dapat dipilih] boolean PALSU TIDAK Izinkan untuk memilih grup ketika groupBy digunakan
[GroupAsModel yang dapat dipilih] boolean BENAR TIDAK Menunjukkan apakah akan memilih semua anak atau kelompok itu sendiri
[item] Array<any> [] Ya Susunan item
[memuat] boolean - TIDAK Anda dapat mengatur status pemuatan dari luar (misalnya pemuatan item asinkron)
memuatTeks string Loading... TIDAK Atur teks khusus saat memuat item
labelUntukId string - TIDAK Id untuk mengaitkan kontrol dengan label.
[tandaiPertama] boolean true TIDAK Menandai item pertama sebagai fokus saat membuka/memfilter.
[terbuka] boolean - TIDAK Memungkinkan kontrol manual pembukaan dan penutupan dropdown. true - tidak akan menutup. false - tidak akan terbuka.
maxSelectedItems number tidak ada TIDAK Ketika kelipatan = benar, memungkinkan untuk menetapkan batas jumlah pilihan.
[sembunyikan yang dipilih] boolean false TIDAK Memungkinkan untuk menyembunyikan item yang dipilih.
[beberapa] boolean false TIDAK Memungkinkan untuk memilih beberapa item.
notFoundText string No items found TIDAK Tetapkan teks khusus ketika filter mengembalikan hasil kosong
pengganti string - TIDAK Teks pengganti.
[dapat dicari] boolean true TIDAK Izinkan untuk mencari nilai. Standarnya true
[hanya baca] boolean false TIDAK Setel ng-pilih sebagai hanya baca. Kebanyakan digunakan dengan bentuk reaktif.
[pencarianFn] (term: string, item: any) => boolean null TIDAK Izinkan untuk memfilter berdasarkan fungsi pencarian khusus
[pencarian Sambil Menulis] boolean true TIDAK Apakah item harus difilter saat komposisi dimulai
[trackByFn] (item: any) => any null TIDAK Menyediakan fungsi trackBy khusus
[hapusSearchOnAdd] boolean true TIDAK Menghapus input pencarian saat item dipilih. Standarnya true . Defaultnya false ketika closeOnSelect false
[batalkan pilihanOnClick] boolean false TIDAK Membatalkan pilihan item yang dipilih ketika diklik di dropdown. Bawaan false . Defaultnya true jika kelipatannya true
[Istilah Pencarian yang dapat diedit] boolean false TIDAK Izinkan untuk mengedit permintaan pencarian jika opsi dipilih. Bawaan false . Hanya berfungsi jika multiple bernilai false .
[pilihDiTab] boolean false TIDAK Pilih item dropdown yang ditandai menggunakan tab. Bawaan false
[bukaDiEnter] boolean true TIDAK Buka tarik-turun menggunakan enter. Standarnya true
[mengetik terlebih dahulu] Subject - TIDAK Pelengkapan otomatis khusus atau filter lanjutan.
[panjang jangka waktu tertentu] number 0 TIDAK Panjang jangka waktu minimum untuk memulai pencarian. Harus digunakan dengan typeahead
ketikToSearchText string Type to search TIDAK Atur teks khusus saat menggunakan Typeahead
[Gulir virtual] boolean PALSU TIDAK Aktifkan gulir virtual untuk kinerja yang lebih baik saat merender banyak data
[inputAttrs] { [key: string]: string } - TIDAK Berikan atribut khusus ke elemen input yang mendasarinya
[tabIndeks] number - TIDAK Setel tabindex pada ng-pilih
[mencegahToggleOnRightClick] boolean false TIDAK Cegah pembukaan ng-select pada klik kanan mouse
[kunciDownFn] ($event: KeyboardEvent) => bool true TIDAK Menyediakan fungsi keyDown khusus. Dieksekusi sebelum pengendali default. Kembalikan false untuk menekan eksekusi penangan kunci default

Keluaran

Keluaran Keterangan
(menambahkan) Dipecat saat item ditambahkan saat [multiple]="true" . Menghasilkan item yang ditambahkan
(mengaburkan) Diaktifkan pada blur tertentu
(mengubah) Diaktifkan saat perubahan model. Menghasilkan seluruh model
(menutup) Diaktifkan saat pilih dropdown tutup
(jernih) Diaktifkan pada klik ikon yang jelas
(fokus) Diaktifkan pada fokus yang dipilih
(mencari) Dipecat saat mengetik istilah pencarian. Menghasilkan istilah pencarian dengan item yang difilter
(membuka) Diaktifkan saat pilih dropdown terbuka
(menghapus) Dipecat saat item dihapus saat [multiple]="true"
(menggulir) Dipecat saat di-scroll. Memberikan indeks awal dan akhir dari item yang tersedia saat ini. Dapat digunakan untuk memuat lebih banyak item dalam beberapa bagian sebelum pengguna menggulir hingga ke bagian bawah daftar.
(gulir Ke Akhir) Dipicu saat di-scroll ke akhir item. Dapat digunakan untuk memuat lebih banyak item dalam potongan.

Metode

Nama Keterangan
membuka Membuka panel tarik-turun pilih
menutup Menutup panel tarik-turun pilih
fokus Memfokuskan elemen pilihan
mengaburkan Mengaburkan elemen pilihan

Lainnya

Nama Jenis Keterangan
[ngOptionSorotan] direktif Sorot istilah pencarian dalam opsi. Menerima istilah pencarian. Harus digunakan pada elemen opsi. BACA SAYA
NgSelectConfig konfigurasi Penyedia konfigurasi untuk komponen NgSelect. Anda dapat memasukkan layanan ini dan menyediakan konfigurasi luas aplikasi.
SELECTION_MODEL_FACTORY melayani Token DI untuk implementasi SelectionModel. Anda dapat memberikan implementasi khusus yang mengubah perilaku pemilihan.

Logika pemilihan khusus

Ng-select memungkinkan untuk menyediakan implementasi pemilihan khusus menggunakan SELECTION_MODEL_FACTORY . Untuk mengganti logika default, berikan metode pabrik Anda di modul sudut Anda. 

 // app.module.ts
providers: [
    { provide : SELECTION_MODEL_FACTORY , useValue : < SelectionModelFactory > CustomSelectionFactory }
]

// selection-model.ts
export function CustomSelectionFactory ( ) {
    return new CustomSelectionModel ( ) ;
}

export class CustomSelectionModel implements SelectionModel {
    ...
}

Ubah Deteksi

Komponen Ng-select mengimplementasikan deteksi perubahan OnPush yang berarti pemeriksaan kotor memeriksa tipe data yang tidak dapat diubah. Artinya jika Anda melakukan mutasi objek seperti: 

 this . items . push ( { id : 1 , name : 'New item' } )

Komponen tidak akan mendeteksi perubahan. Sebaliknya, Anda perlu melakukan: 

 this . items = [ ... this . items , { id : 1 , name : 'New item' } ] ;

Ini akan menyebabkan komponen mendeteksi perubahan dan pembaruan. Beberapa orang mungkin khawatir bahwa ini adalah operasi yang mahal, namun, kinerjanya jauh lebih baik daripada menjalankan ngDoCheck dan terus-menerus melakukan diffing array.

Gaya khusus

Jika Anda tidak puas dengan gaya default, Anda dapat dengan mudah menggantinya dengan peningkatan kekhususan pemilih atau membuat tema Anda sendiri. Ini berlaku jika Anda tidak menggunakan ViewEncapsulation atau menambahkan gaya ke stylesheet global. Misalnya 

 < ng-select class =" custom " > </ ng-select > 
. ng-select . custom {
    border : 0 px ;
    min-height : 0 px ;
    border-radius : 0 ;
}
. ng-select . custom . ng-select-container  {            
    min-height : 0 px ;
    border-radius : 0 ;
}

Jika Anda menggunakan ViewEncapsulation , Anda dapat menggunakan pemilih ::ng-deep khusus yang akan mencegah pelingkupan untuk penyeleksi bersarang meskipun ini lebih merupakan solusi dan kami menyarankan penggunaan solusi yang dijelaskan di atas. 

. ng-select . custom :: ng-deep . ng-select-container  {            
    min-height : 0 px ;
    border-radius : 0 ;
}

PERINGATAN: Ingatlah bahwa ng-deep sudah tidak digunakan lagi dan belum ada alternatif lain selain itu. Lihat Disini.

Status validasi

Secara default ketika Anda menggunakan validator formulir reaktif atau validator formulir berbasis templat, kelas css ng-invalid akan diterapkan pada ng-select. Anda dapat menampilkan status kesalahan dengan menambahkan gaya css khusus 

 ng-select . ng-invalid . ng-touched . ng-select-container {
    border-color : # dc3545 ;
    box-shadow : inset 0 1 px 1 px rgba ( 0 , 0 , 0 , 0.075 ) , 0 0 0 3 px # fde6e8 ;
}

Berkontribusi

Kontribusi dipersilakan. Anda dapat memulai dengan melihat masalah dengan label Dibutuhkan bantuan atau membuat Masalah baru dengan proposal atau laporan bug. Perhatikan bahwa kami menggunakan format komitmen https://conventionalcommits.org/.

Perkembangan

Lakukan langkah-langkah kloning untuk meluncurkan dengan perintah terminal ini.

Jalankan halaman demo dalam mode tontonan 

 git clone https://github.com/ng-select/ng-select
cd ng-select
yarn
yarn run start

Pengujian 

 yarn run test
or
yarn run test:watch

Melepaskan

Untuk melepaskan ke npm jalankan saja ./release.sh , tentu saja jika Anda memiliki izin;)

Inspirasi

Komponen ini terinspirasi oleh React select dan Virtual scroll. Periksa karya dan komponen mereka yang luar biasa :)

Memperluas
Informasi Tambahan
Aplikasi Terkait
Direkomendasikan untuk Anda
Informasi Terkait Semua