ng select
v14.0.0
Consulte la página de demostración.
| Angular | ng-seleccionar |
|---|---|
| >=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 admite todos los navegadores compatibles con Angular. Para ver la lista actual, consulte https://angular.io/guide/browser-support#browser-support. Esto incluye las siguientes versiones específicas:
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 biblioteca está en desarrollo activo y puede tener cambios importantes en la API para versiones principales posteriores a 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 { } Para permitir la personalización y la temática, el paquete ng-select incluye solo estilos genéricos que son necesarios para un diseño y posicionamiento correctos. Para obtener una visión completa del control, incluya uno de los temas en su aplicación. Si está utilizando Angular CLI, puede agregarlo a su styles.scss o incluirlo en .angular-cli.json (Angular v5 y versiones anteriores) o angular.json (Angular v6 en adelante).
@import " ~@ng-select/ng-select/themes/default.theme.css " ;
// ... or
@import " ~@ng-select/ng-select/themes/material.theme.css " ;
También puede establecer mensajes de configuración y localización global inyectando el servicio NgSelectConfig, generalmente en su componente raíz, y personalizar los valores de sus propiedades para proporcionar valores predeterminados.
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' ;
}Defina opciones en su componente de consumo:
@ Component ( { ... } )
export class ExampleComponent {
selectedCar : number ;
cars = [
{ id : 1 , name : 'Volvo' } ,
{ id : 2 , name : 'Saab' } ,
{ id : 3 , name : 'Opel' } ,
{ id : 4 , name : 'Audi' } ,
] ;
} En la plantilla use el componente ng-select con sus opciones
<!--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 >Para obtener ejemplos más detallados, consulte la página de demostración.
Si está utilizando SystemJS, también debe ajustar su configuración para que apunte al paquete UMD.
En su archivo de configuración systemjs, map debe indicarle al cargador del sistema dónde buscar ng-select :
map: {
'@ng-select/ng-select' : 'node_modules/@ng-select/ng-select/bundles/ng-select.umd.js' ,
} | Aporte | Tipo | Por defecto | Requerido | Descripción |
|---|---|---|---|---|
| [agregar etiqueta] | boolean | ((term: string) => any | Promise<any>) | false | No | Permite crear opciones personalizadas. |
| agregar texto de etiqueta | string | Add item | No | Establecer texto personalizado al usar etiquetas |
| apariencia | string | underline | No | Permite seleccionar la apariencia del menú desplegable. Establecer outline para agregar borde en lugar de subrayado (se aplica solo al tema Material) |
| anexar a | string | nulo | No | Agregue el menú desplegable al cuerpo o cualquier otro elemento usando el selector CSS. Para un posicionamiento correcto body debe tener position:relative |
| cantidad de buffer | string | nulo | No | Agregue el menú desplegable al cuerpo o cualquier otro elemento usando el selector CSS. Para un posicionamiento correcto body debe tener position:relative |
| valor de vinculación | string | - | No | Propiedad del objeto que se utilizará para el modelo seleccionado. De forma predeterminada se vincula a todo el objeto. |
| enlazaretiqueta | string | label | No | Propiedad del objeto que se utilizará para la etiqueta. label predeterminada |
| [cerrarOnSelect] | boolean | verdadero | No | Si cerrar el menú cuando se selecciona un valor |
| borrar todo el texto | string | Clear all | No | Establecer texto personalizado para borrar todos los títulos de íconos |
| [borrable] | boolean | true | No | Permitir borrar el valor seleccionado. true predeterminado |
| [clearOnBackspace] | boolean | true | No | Borre los valores seleccionados uno por uno al hacer clic en Retroceso. true predeterminado |
| [comparar con] | (a: any, b: any) => boolean | (a, b) => a === b | No | Una función para comparar los valores de las opciones con los valores seleccionados. El primer argumento es un valor de una opción. El segundo es un valor de la selección (modelo). Se debe devolver un booleano. |
| posición desplegable | bottom | top | auto | auto | No | Establecer la posición desplegable en abierto |
| [marcador de posición fijo] | boolean | false | No | Establecer marcador de posición visible incluso cuando se selecciona un elemento |
| [grupoPor] | string | Function | nulo | No | Permitir agrupar elementos por clave o expresión de función |
| [valor de grupo] | (groupKey: string, children: any[]) => Object | - | No | Expresión de función para proporcionar valor de grupo. |
| [grupo seleccionable] | boolean | FALSO | No | Permitir seleccionar grupo cuando se utiliza groupBy |
| [Grupo seleccionable como modelo] | boolean | verdadero | No | Indica si se seleccionan todos los niños o el grupo en sí. |
| [elementos] | Array<any> | [] | Sí | Matriz de elementos |
| [cargando] | boolean | - | No | Puede configurar el estado de carga desde el exterior (por ejemplo, carga de elementos asíncronos) |
| cargandoTexto | string | Loading... | No | Establecer texto personalizado al cargar elementos |
| etiquetaParaId | string | - | No | Id. para asociar el control con la etiqueta. |
| [marcarPrimero] | boolean | true | No | Marca el primer elemento como enfocado al abrir/filtrar. |
| [está abierto] | boolean | - | No | Permite el control manual de apertura y cierre del desplegable. true : no se cierra. false : no se abre. |
| maxSelectedItems | number | ninguno | No | Cuando multiple = true, permite establecer un número límite de selección. |
| [ocultarSeleccionado] | boolean | false | No | Permite ocultar elementos seleccionados. |
| [múltiple] | boolean | false | No | Permite seleccionar múltiples elementos. |
| textonoencontrado | string | No items found | No | Establecer texto personalizado cuando el filtro devuelve un resultado vacío |
| marcador de posición | string | - | No | Texto de marcador de posición. |
| [buscable] | boolean | true | No | Permitir buscar valor. true predeterminado |
| [solo lectura] | boolean | false | No | Establezca ng-select como de solo lectura. Se utiliza principalmente con formas reactivas. |
| [buscarFn] | (term: string, item: any) => boolean | null | No | Permitir filtrar por función de búsqueda personalizada |
| [buscar mientras se compone] | boolean | true | No | Si los elementos deben filtrarse mientras se inicia la composición |
| [pistaPorFn] | (item: any) => any | null | No | Proporcionar función trackBy personalizada |
| [borrarSearchOnAdd] | boolean | true | No | Borra la entrada de búsqueda cuando se selecciona el elemento. Por defecto true . false predeterminado cuando closeOnSelect es false |
| [deseleccionarAlHacerClic] | boolean | false | No | Deselecciona un elemento seleccionado cuando se hace clic en él en el menú desplegable. Por defecto false . true predeterminado cuando múltiples son true |
| [Término de búsqueda editable] | boolean | false | No | Permitir editar la consulta de búsqueda si se selecciona la opción. Por defecto false . Funciona sólo si multiple es false . |
| [seleccionar en la pestaña] | boolean | false | No | Seleccione el elemento desplegable marcado usando la pestaña. false predeterminado |
| [abrirAlEntrar] | boolean | true | No | Abra el menú desplegable usando enter. true predeterminado |
| [escribir anticipadamente] | Subject | - | No | Autocompletado personalizado o filtro avanzado. |
| [minTermLength] | number | 0 | No | Longitud mínima del término para iniciar una búsqueda. Debe usarse con typeahead |
| escribirParaBuscarTexto | string | Type to search | No | Establecer texto personalizado al usar Typeahead |
| [desplazamiento virtual] | boolean | FALSO | No | Habilite el desplazamiento virtual para un mejor rendimiento al renderizar una gran cantidad de datos |
| [atributos de entrada] | { [key: string]: string } | - | No | Pasar atributos personalizados al elemento input subyacente |
| [pestañaÍndice] | number | - | No | Establecer índice de tabulación en ng-select |
| [evitarToggleOnRightClick] | boolean | false | No | Evitar la apertura de ng-select al hacer clic con el botón derecho del mouse |
| [teclaAbajoFn] | ($event: KeyboardEvent) => bool | true | No | Proporcionar función keyDown personalizada. Ejecutado antes del controlador predeterminado. Devuelve falso para suprimir la ejecución de los controladores de teclas predeterminados. |
| Producción | Descripción |
|---|---|
| (agregar) | Se activa cuando se agrega un elemento mientras [multiple]="true" . Salidas elemento agregado |
| (difuminar) | Disparado en desenfoque seleccionado |
| (cambiar) | Disparado por cambio de modelo. Genera todo el modelo |
| (cerca) | Activado al cerrar el menú desplegable seleccionado |
| (claro) | Se dispara al hacer clic en el icono de borrar |
| (enfocar) | Disparado en foco seleccionado |
| (buscar) | Se disparó al escribir un término de búsqueda. Genera un término de búsqueda con elementos filtrados. |
| (abierto) | Activado al abrir el menú desplegable seleccionado |
| (eliminar) | Se activa cuando se elimina el elemento mientras [multiple]="true" |
| (voluta) | Se dispara cuando se desplaza. Proporciona el índice inicial y final de los elementos disponibles actualmente. Se puede utilizar para cargar más elementos en fragmentos antes de que el usuario se haya desplazado hasta el final de la lista. |
| (desplazarse hasta el final) | Se activa cuando se desplaza hasta el final de los elementos. Se puede utilizar para cargar más elementos en trozos. |
| Nombre | Descripción |
|---|---|
| abierto | Abre el panel desplegable de selección. |
| cerca | Cierra el panel desplegable de selección. |
| enfocar | Enfoca el elemento seleccionado. |
| difuminar | Desenfoca el elemento seleccionado |
| Nombre | Tipo | Descripción |
|---|---|---|
| [ngOptionHighlight] | directiva | Destaca el término de búsqueda en la opción. Acepta término de búsqueda. Debe usarse en el elemento de opción. LÉAME |
| NgSelectConfig | configuración | Proveedor de configuración para el componente NgSelect. Puede inyectar este servicio y proporcionar una configuración para toda la aplicación. |
| SELECTION_MODEL_FACTORY | servicio | Token DI para la implementación de SelectionModel. Puede proporcionar una implementación personalizada que cambie el comportamiento de selección. |
Ng-select permite proporcionar una implementación de selección personalizada utilizando SELECTION_MODEL_FACTORY . Para anular la lógica predeterminada, proporcione su método de fábrica en su módulo angular.
// 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 {
...
} El componente ng-select implementa la detección de cambios OnPush , lo que significa que la verificación sucia busca tipos de datos inmutables. Eso significa que si haces mutaciones de objetos como:
this . items . push ( { id : 1 , name : 'New item' } )El componente no detectará un cambio. En su lugar, debes hacer:
this . items = [ ... this . items , { id : 1 , name : 'New item' } ] ; Esto hará que el componente detecte el cambio y lo actualice. A algunos les podría preocupar que esta sea una operación costosa; sin embargo, es mucho más eficaz que ejecutar ngDoCheck y diferenciar constantemente la matriz.
Si no está satisfecho con los estilos predeterminados, puede anularlos fácilmente con una mayor especificidad del selector o creando su propio tema. Esto se aplica si no utiliza ViewEncapsulation o agrega estilos a la hoja de estilos global. P.ej
< 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 está utilizando ViewEncapsulation , puede usar un selector especial ::ng-deep que evitará el alcance de los selectores anidados, aunque esto es más bien una solución alternativa y recomendamos usar la solución descrita anteriormente.
. ng-select . custom :: ng-deep . ng-select-container {
min-height : 0 px ;
border-radius : 0 ;
}ADVERTENCIA: Tenga en cuenta que ng-deep está en desuso y todavía no existe ninguna alternativa. Ver aquí.
De forma predeterminada, cuando utiliza validadores de formularios reactivos o validadores de formularios basados en plantillas, la clase CSS ng-invalid se aplicará en ng-select. Puede mostrar el estado de los errores agregando un estilo CSS personalizado
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 ;
}Las contribuciones son bienvenidas. Puede comenzar mirando los problemas con la etiqueta Se busca ayuda o creando un nuevo problema con propuesta o informe de error. Tenga en cuenta que estamos utilizando el formato de confirmación https://conventionalcommits.org/.
Realice los pasos de clonación para iniciar con estos comandos 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
Para liberar a npm simplemente ejecute ./release.sh , por supuesto, si tiene permisos;)
Este componente está inspirado en React select y Virtual scroll. Mira su increíble trabajo y componentes :)
