ng select
v14.0.0
Voir la page Démo.
| Angulaire | ng-sélectionner |
|---|---|
| >=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 |
ng-select prend en charge tous les navigateurs pris en charge par Angular. Pour la liste actuelle, consultez https://angular.io/guide/browser-support#browser-support. Cela inclut les versions spécifiques suivantes :
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
La bibliothèque est en cours de développement actif et peut avoir des modifications de rupture d'API pour les versions majeures ultérieures après la 1.0.0.
ng-select : npm install --save @ng-select/ng-selectyarn add @ng-select/ng-select 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 { } import { NgSelectModule } from '@ng-select/ng-select' ;
import { FormsModule } from '@angular/forms' ;
@ NgModule ( {
declarations : [ AppComponent ] ,
imports : [ NgSelectModule , FormsModule ] ,
bootstrap : [ AppComponent ]
} )
export class AppModule { } Pour permettre la personnalisation et la création de thèmes, le bundle ng-select inclut uniquement les styles génériques nécessaires à une mise en page et un positionnement corrects. Pour obtenir un aperçu complet du contrôle, incluez l’un des thèmes dans votre application. Si vous utilisez Angular CLI, vous pouvez l'ajouter à votre styles.scss ou l'inclure dans .angular-cli.json (Angular v5 et versions antérieures) ou angular.json (Angular v6 et versions ultérieures).
@import " ~@ng-select/ng-select/themes/default.theme.css " ;
// ... or
@import " ~@ng-select/ng-select/themes/material.theme.css " ;
Vous pouvez également définir des messages de configuration globale et de localisation en injectant le service NgSelectConfig, généralement dans votre composant racine, et personnaliser les valeurs de ses propriétés afin de fournir des valeurs par défaut.
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' ;
}Définissez les options dans votre composant consommateur :
@ Component ( { ... } )
export class ExampleComponent {
selectedCar : number ;
cars = [
{ id : 1 , name : 'Volvo' } ,
{ id : 2 , name : 'Saab' } ,
{ id : 3 , name : 'Opel' } ,
{ id : 4 , name : 'Audi' } ,
] ;
} Dans le modèle, utilisez le composant ng-select avec vos options
<!--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 >Pour des exemples plus détaillés, voir la page Démo
Si vous utilisez SystemJS, vous devez également ajuster votre configuration pour pointer vers le bundle UMD.
Dans votre fichier de configuration systemjs, map doit indiquer au chargeur système où chercher ng-select :
map: {
'@ng-select/ng-select' : 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js' ,
} | Saisir | Taper | Défaut | Requis | Description |
|---|---|---|---|---|
| [ajouter une balise] | boolean | ((term: string) => any | Promise<any>) | false | Non | Permet de créer des options personnalisées. |
| ajouterTagText | string | Add item | Non | Définir un texte personnalisé lors de l'utilisation du balisage |
| apparence | string | underline | Non | Permet de sélectionner l'apparence de la liste déroulante. Définir sur outline pour ajouter une bordure au lieu de souligner (s'applique uniquement au thème Matériau) |
| ajouterÀ | string | nul | Non | Ajoutez la liste déroulante au corps ou à tout autre élément à l'aide du sélecteur CSS. Pour un positionnement correct, body doit avoir position:relative |
| montanttampon | string | nul | Non | Ajoutez la liste déroulante au corps ou à tout autre élément à l'aide du sélecteur CSS. Pour un positionnement correct, body doit avoir position:relative |
| valeur de liaison | string | - | Non | Propriété d'objet à utiliser pour le modèle sélectionné. Par défaut, se lie à l'objet entier. |
| bindLabel | string | label | Non | Propriété d'objet à utiliser pour l'étiquette. label par défaut |
| [fermer sur sélection] | boolean | vrai | Non | S'il faut fermer le menu lorsqu'une valeur est sélectionnée |
| effacerToutTexte | string | Clear all | Non | Définir un texte personnalisé pour effacer tous les titres des icônes |
| [effaçable] | boolean | true | Non | Autoriser à effacer la valeur sélectionnée. true par défaut |
| [effacerOnBackspace] | boolean | true | Non | Effacez les valeurs sélectionnées une par une lorsque vous cliquez sur Retour arrière. true par défaut |
| [comparerAvec] | (a: any, b: any) => boolean | (a, b) => a === b | Non | Une fonction pour comparer les valeurs des options avec les valeurs sélectionnées. Le premier argument est une valeur d'une option. La seconde est une valeur de la sélection (modèle). Un booléen doit être renvoyé. |
| position déroulante | bottom | top | auto | auto | Non | Réglez la position déroulante sur ouvert |
| [fixedPlaceholder] | boolean | false | Non | Définir un espace réservé visible même lorsqu'un élément est sélectionné |
| [groupePar] | string | Function | nul | Non | Autoriser le regroupement d'éléments par clé ou expression de fonction |
| [valeurgroupe] | (groupKey: string, children: any[]) => Object | - | Non | Expression de fonction pour fournir une valeur de groupe |
| [Groupe sélectionnable] | boolean | FAUX | Non | Autoriser la sélection d'un groupe lorsque groupBy est utilisé |
| [selectableGroupAsModel] | boolean | vrai | Non | Indique s'il faut sélectionner tous les enfants ou le groupe lui-même |
| [articles] | Array<any> | [] | Oui | Tableau d'éléments |
| [chargement] | boolean | - | Non | Vous pouvez définir l'état de chargement de l'extérieur (par exemple, chargement d'éléments asynchrones) |
| chargement du texte | string | Loading... | Non | Définir un texte personnalisé lors du chargement des éléments |
| labelForId | string | - | Non | Identifiant pour associer le contrôle à l’étiquette. |
| [marquer en premier] | boolean | true | Non | Marque le premier élément comme étant ciblé lors de l’ouverture/du filtrage. |
| [estOuvert] | boolean | - | Non | Permet le contrôle manuel de l'ouverture et de la fermeture du menu déroulant. true - ne fermera pas. false - ne s'ouvre pas. |
| maxSelectedItems | number | aucun | Non | Lorsque multiple = true, permet de définir un nombre limite de sélection. |
| [masquer la sélection] | boolean | false | Non | Permet de masquer les éléments sélectionnés. |
| [multiple] | boolean | false | Non | Permet de sélectionner plusieurs éléments. |
| textenotFound | string | No items found | Non | Définir un texte personnalisé lorsque le filtre renvoie un résultat vide |
| espace réservé | string | - | Non | Texte d'espace réservé. |
| [consultable] | boolean | true | Non | Permet de rechercher une valeur. true par défaut |
| [lecture seule] | boolean | false | Non | Définissez ng-select en lecture seule. Principalement utilisé avec des formes réactives. |
| [rechercheFn] | (term: string, item: any) => boolean | null | Non | Autoriser le filtrage par fonction de recherche personnalisée |
| [recherche pendant la composition] | boolean | true | Non | Si les éléments doivent être filtrés au démarrage de la composition |
| [pisteByFn] | (item: any) => any | null | Non | Fournir une fonction trackBy personnalisée |
| [clearSearchOnAdd] | boolean | true | Non | Efface l’entrée de recherche lorsque l’élément est sélectionné. true par défaut. false par défaut lorsque closeOnSelect est false |
| [désélectionnerSurClic] | boolean | false | Non | Désélectionne un élément sélectionné lorsque vous cliquez dessus dans la liste déroulante. false par défaut. true par défaut lorsque plusieurs sont true |
| [terme de recherche modifiable] | boolean | false | Non | Autoriser la modification de la requête de recherche si l'option est sélectionnée. false par défaut. Fonctionne uniquement si multiple est false . |
| [sélectionnerSurTab] | boolean | false | Non | Sélectionnez l’élément déroulant marqué à l’aide de l’onglet. false par défaut |
| [ouvrir sur Entrée] | boolean | true | Non | Ouvrez la liste déroulante en utilisant Entrée. true par défaut |
| [saisie] | Subject | - | Non | Saisie semi-automatique personnalisée ou filtre avancé. |
| [minTermLongueur] | number | 0 | Non | Longueur minimale du terme pour lancer une recherche. Doit être utilisé avec typeahead |
| tapezVersTexteRecherche | string | Type to search | Non | Définir un texte personnalisé lors de l'utilisation de Typeahead |
| [Défilement virtuel] | boolean | FAUX | Non | Activer le défilement virtuel pour de meilleures performances lors du rendu de beaucoup de données |
| [entréeAttrs] | { [key: string]: string } | - | Non | Transmettre des attributs personnalisés à l'élément input sous-jacent |
| [ongletIndex] | number | - | Non | Définir tabindex sur ng-select |
| [empêcherToggleOnRightClick] | boolean | false | Non | Empêcher l'ouverture de ng-select lors d'un clic droit de la souris |
| [keyDownFn] | ($event: KeyboardEvent) => bool | true | Non | Fournit une fonction keyDown personnalisée. Exécuté avant le gestionnaire par défaut. Renvoie false pour supprimer l'exécution des gestionnaires de touches par défaut |
| Sortir | Description |
|---|---|
| (ajouter) | Déclenché lorsque l'élément est ajouté while [multiple]="true" . Élément ajouté aux sorties |
| (se brouiller) | Déclenché sur un flou sélectionné |
| (changement) | Licencié suite à un changement de modèle. Produit le modèle entier |
| (fermer) | Lancé à la fermeture de la liste déroulante de sélection |
| (clair) | Lancé en cliquant sur l'icône Effacer |
| (se concentrer) | Tiré sur le focus sélectionné |
| (recherche) | Lancé lors de la saisie du terme de recherche. Affiche le terme de recherche avec les éléments filtrés |
| (ouvrir) | Lancé lors de l'ouverture de la liste déroulante de sélection |
| (retirer) | Lancé lorsque l'élément est supprimé alors que [multiple]="true" |
| (rouleau) | Lancé lors du défilement. Fournit l’index de début et de fin des éléments actuellement disponibles. Peut être utilisé pour charger plus d’éléments en morceaux avant que l’utilisateur n’ait fait défiler jusqu’en bas de la liste. |
| (faire défiler jusqu'à la fin) | Lancé lors d'un défilement jusqu'à la fin des éléments. Peut être utilisé pour charger plus d’éléments en morceaux. |
| Nom | Description |
|---|---|
| ouvrir | Ouvre le panneau déroulant de sélection |
| fermer | Ferme le panneau déroulant de sélection |
| se concentrer | Focuse l'élément sélectionné |
| se brouiller | Brouille l'élément sélectionné |
| Nom | Taper | Description |
|---|---|---|
| [ngOptionHighlight] | directif | Met en surbrillance le terme de recherche en option. Accepte le terme de recherche. Doit être utilisé sur l’élément d’option. LISEZMOI |
| NgSelectConfig | configuration | Fournisseur de configuration pour le composant NgSelect. Vous pouvez injecter ce service et fournir une configuration à l’échelle de l’application. |
| SELECTION_MODEL_FACTORY | service | Jeton DI pour l’implémentation de SelectionModel. Vous pouvez fournir une implémentation personnalisée modifiant le comportement de sélection. |
Ng-select permet de fournir une implémentation de sélection personnalisée en utilisant SELECTION_MODEL_FACTORY . Pour remplacer la logique par défaut, fournissez votre méthode d'usine dans votre module angulaire.
// 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 {
...
} Le composant Ng-select implémente la détection des modifications OnPush , ce qui signifie que la vérification sale vérifie les types de données immuables. Cela signifie que si vous effectuez des mutations d'objets telles que :
this . items . push ( { id : 1 , name : 'New item' } )Le composant ne détectera pas de changement. Au lieu de cela, vous devez faire :
this . items = [ ... this . items , { id : 1 , name : 'New item' } ] ; Cela permettra au composant de détecter le changement et de le mettre à jour. Certains pourraient craindre qu'il s'agisse d'une opération coûteuse, cependant, elle est beaucoup plus performante que d'exécuter ngDoCheck et de comparer constamment le tableau.
Si vous n'êtes pas satisfait des styles par défaut, vous pouvez facilement les remplacer par une spécificité de sélecteur accrue ou en créant votre propre thème. Cela s'applique si vous n'utilisez pas ViewEncapsulation ou si vous ajoutez des styles à la feuille de style globale. Par exemple
< 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 ;
} Si vous utilisez ViewEncapsulation , vous pouvez utiliser un sélecteur spécial ::ng-deep qui empêchera la portée des sélecteurs imbriqués, bien qu'il s'agisse plutôt d'une solution de contournement et nous vous recommandons d'utiliser la solution décrite ci-dessus.
. ng-select . custom :: ng-deep . ng-select-container {
min-height : 0 px ;
border-radius : 0 ;
}AVERTISSEMENT : gardez à l'esprit que ng-deep est obsolète et qu'il n'existe pas encore d'alternative. Voir ici.
Par défaut, lorsque vous utilisez des validateurs de formulaires réactifs ou des validateurs de formulaires basés sur des modèles, la classe CSS ng-invalid sera appliquée sur ng-select. Vous pouvez afficher l'état des erreurs en ajoutant un style CSS personnalisé
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 ;
}Les contributions sont les bienvenues. Vous pouvez commencer par examiner les problèmes avec l'étiquette Aide recherchée ou créer un nouveau problème avec une proposition ou un rapport de bogue. Notez que nous utilisons le format de commits https://conventionalcommits.org/.
Effectuez les étapes du clonage au lancement avec ces commandes de terminal.
git clone https://github.com/ng-select/ng-select
cd ng-select
yarn
yarn run start
yarn run test
or
yarn run test:watch
Pour publier sur npm, exécutez simplement ./release.sh , bien sûr si vous disposez des autorisations ;)
Ce composant s'inspire de React select et Virtual scroll. Vérifiez leur travail et leurs composants incroyables :)
