Descripción general del componente ComboBox de selección única Angular
El componente ComboBox de selección única Angular es una modificación del componente ComboBox que permite una selección única. Lo llamamos "combo simple". Debido a la alta demanda del modo de selección única para el componente ComboBox original, creamos un componente de extensión que ofrece una entrada de búsqueda editable que permite a los usuarios elegir una opción de una lista predefinida de elementos e ingresar valores personalizados.
Ejemplo de cuadro combinado simple Angular
En este ejemplo de cuadro combinado simple Angular, puede ver cómo los usuarios pueden seleccionar el tipo de línea de tendencia del gráfico. Además, el cuadro combinado simple muestra la navegación mediante teclado y las capacidades de estilo personalizado.
¿Te gusta esta muestra? Obtenga acceso a nuestro kit de herramientas de Ignite UI for Angular completo y comience a crear sus propias aplicaciones en minutos. Descárgalo gratis.
Características de Simple ComboBox Angular
El control de cuadro combinado simple expone las siguientes características: - Enlace de datos - datos locales y datos remotos - Enlace de valores - Filtrado - Agrupación - Valores personalizados - Plantillas - Integración con formularios basados en plantillas y formularios reactivos
Primeros pasos con Ignite UI for Angular ComboBox Simple
Para comenzar con el componente Ignite UI for Angular Simple ComboBox, primero debe instalar Ignite UI for Angular. En una aplicación Angular existente, escriba el siguiente comando:
ng add igniteui-angular
cmd
Para obtener una introducción completa al Ignite UI for Angular, lea el tema de introducción.
El siguiente paso es importar IgxSimpleComboModule
en su archivo app.module.ts.
import { IgxSimpleComboModule } from 'igniteui-angular';
// import { IgxSimpleComboModule } from '@infragistics/igniteui-angular'; for licensed package
@NgModule({
imports: [
...
IgxSimpleComboModule,
...
]
})
export class AppModule {}
typescript
Alternativamente, a partir de 16.0.0
, puede importar IgxSimpleComboComponent
como una dependencia independiente o usar el token IGX_SIMPLE_COMBO_DIRECTIVES
para importar el componente y todos sus componentes y directivas de soporte.
// home.component.ts
import { IGX_SIMPLE_COMBO_DIRECTIVES } from 'igniteui-angular';
// import { IGX_SIMPLE_COMBO_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package
@Component({
selector: 'app-home',
template: '<igx-simple-combo></igx-simple-combo>',
styleUrls: ['home.component.scss'],
standalone: true,
imports: [IGX_SIMPLE_COMBO_DIRECTIVES]
/* or imports: [IgxSimpleComboComponent] */
})
export class HomeComponent {}
typescript
Ahora que tiene el módulo o las directivas Ignite UI for Angular Simple ComboBox importados, puede comenzar a usar el igx-simple-combo
componente.
Uso del cuadro combinado simple Angular
Al igual que el cuadro combinado normal, puede vincular el combo igx-simple a los datos.
export class MySimpleComboComponent implements OnInit {
public cities: City[];
public ngOnInit() {
this.cities = getCitiesByPopulation(10000000);
}
}
typescript
<igx-simple-combo [data]="cities"></igx-simple-combo>
html
Nuestro cuadro combinado simple ahora está vinculado a la variedad de ciudades.
Valor de datos y propiedades de visualización
Dado que el cuadro combinado simple está vinculado a una matriz de datos complejos (es decir, objetos), necesitamos especificar una propiedad que el control utilizará para manejar los elementos seleccionados. El control expone dos propiedades @Input
: valueKey y displayKey:
valueKey
: opcional, recomendado para matrices de objetos: especifica qué propiedad de las entradas de datos se almacenará para la selección del cuadro combinado simple. Si se omitevalueKey
, el valor del cuadro combinado simple utilizará referencias a las entradas de datos (es decir, la selección será una matriz de entradas deigxSimpleCombo.data
).displayKey
: obligatorio para matrices de objetos: especifica qué propiedad se utilizará para el texto de los elementos. Si no se especifica ningún valor paradisplayKey
, el cuadro combinado simple utilizará lavalueKey
especificada (si corresponde).
En nuestro caso, queremos que el cuadro combinado simple muestre el name
de cada ciudad y su valor para almacenar la id
de cada ciudad. Por lo tanto, vinculamos estas propiedades como valores a displayKey
y valueKey
del cuadro combinado simple, respectivamente:
<igx-simple-combo [data]="cities" [displayKey]="'name'" [valueKey]="'id'"></igx-simple-combo>
html
Cuando la fuente de datos se compone de un tipo simple (por ejemplo, string[]
, number[]
), no especifique valueKey
y displayKey
.
Enlace bidireccional
El componente de cuadro combinado simple admite totalmente el enlace de datos bidireccional con [(ngModel)]
, así como el uso en formularios reactivos y basados en plantillas. Se puede acceder a la selección del cuadro combinado simple mediante enlace bidireccional o mediante la API de selección. Podemos pasar un elemento del mismo tipo que los de la selección del cuadro combinado simple (basado en valueKey
) y cada vez que uno cambia, el otro se actualiza en consecuencia.
En el siguiente ejemplo, inicialmente se seleccionará la primera ciudad de los datos proporcionados. Cualquier cambio adicional en la selección del cuadro combinado simple se reflejará en las selectedCities
.
<igx-simple-combo [data]="cities" [(ngModel)]="selectedCity" [displayKey]="'name'" [valueKey]="'id'"></igx-simple-combo>
html
export class MySimpleComboComponent implements OnInit {
public cities: City[];
public selectedCity: number;
public ngOnInit(): void {
this.cities = getCitiesByPopulation(10000000);
this.selectedCity = this.cities[0].id;
}
}
typescript
El enlace bidireccional también se puede lograr sin una valueKey
especificada. Por ejemplo, si se omite valueKey
, el modelo vinculado tendrá este aspecto:
export class MySimpleComboComponent {
public cities: City[] = [
{ name: 'Sofia', id: '1' }, { name: 'London', id: '2' }, ...];
public selectedCity: City = this.cities[0];
}
typescript
API de selección
El componente de cuadro combinado simple expone una API que permite obtener y manipular el estado de selección actual del control.
Una forma de obtener su selección es mediante la propiedad de selección. Devuelve un valor que corresponde al elemento seleccionado, según la clave de valor especificada (si corresponde).
En nuestro ejemplo, selection
devolverá la id
de la ciudad seleccionada:
export class MySimpleComboComponent {
...
public selection: string = this.simpleCombo.selection;
}
typescript
Usando la API de selección, también puede cambiar el elemento seleccionado del cuadro combinado simple sin interacción del usuario con el control, mediante un clic en un botón, como respuesta a un cambio Observable, etc. Por ejemplo, podemos implementar un botón que selecciona una ciudad, usando el método de selección:
<igx-simple-combo [data]="cities" [displayKey]="'name'" [valueKey]="'id'"></igx-simple-combo>
<button igxButton (click)="selectFavorite()">Select Favorite</button>
html
Cuando se hace clic en el botón, London
se agregará a la selección del cuadro combinado simple:
export class MySimpleComboComponent {
@ViewChild(IgxSimpleComboComponent, { read: IgxSimpleComboComponent, static: true })
public simpleCombo: IgxSimpleComboComponent;
...
selectFavorites(): void {
this.simpleCombo.select('2');
}
}
typescript
El cuadro combinado simple también activa un evento cada vez que cambia su selección: selecciónChanging. Los argumentos del evento emitido, ISimpleComboSelectionChangingEventArgs, contienen información sobre la selección anterior al cambio, la selección actual y el elemento mostrado. El evento también se puede cancelar, impidiendo que se realice la selección.
La vinculación al evento se puede realizar a través de la propiedad @Output
adecuada en la etiqueta igx-simple-combo
:
<igx-simple-combo [data]="cities" [displayKey]="'name'" [valueKey]="'id'"
(selectionChanging)="handleCityChange($event)">
</igx-simple-combo>
html
Navegación por teclado
Cuando el cuadro combinado simple está cerrado y enfocado:
ArrowDown
oAlt
+ArrowDown
abrirán el menú desplegable del cuadro combinado simple.
Cualquier otra pulsación de tecla será manejada por la entrada.
Cuando se abre el cuadro combinado simple y se enfoca un elemento de la lista:
ArrowDown
pasará al siguiente elemento de la lista. Si el elemento activo es el último en la lista y los valores personalizados están habilitados, el foco se moverá al botón Agregar elemento.ArrowUp
se moverá al elemento de la lista anterior. Si el elemento activo es el primero en la lista, el foco volverá a la entrada de búsqueda y al mismo tiempo se seleccionará todo el texto en la entrada.End
se moverá al último elemento de la lista.Home
se moverá al primer elemento de la lista.Space
seleccionará/deseleccionará el elemento de la lista activa.Enter
seleccionará/deseleccionará el elemento de la lista activa y cerrará la lista.Esc
cerrará la lista.
Cuando se abre el cuadro combinado simple y se habilitan los valores personalizados, y el botón Agregar elemento está enfocado:
Enter
agregará un nuevo elemento convalueKey
ydisplayKey
igual al texto en la entrada de búsqueda y seleccionará el nuevo elemento.ArrowUp
moverá el foco nuevamente al último elemento de la lista o, si la lista está vacía, moverá el foco a la entrada.
Escenario en cascada
El siguiente ejemplo demuestra un escenario en el que se utiliza el combo igx-simple:
Echa un vistazo a nuestro ejemplo de cuadrícula Angular con combos en cascada.
Configuración de plantilla
La API del cuadro combinado simple se utiliza para obtener el elemento seleccionado de un componente y cargar la fuente de datos para el siguiente, así como borrar la selección y la fuente de datos cuando sea necesario.
<igx-simple-combo #country
[data]="countriesData"
(selectionChanging)="countryChanging($event)"
placeholder="Choose Country..."
[(ngModel)]="selectedCountry"
[displayKey]="'name'">
</igx-simple-combo>
<igx-simple-combo #region
[data]="regionData"
(selectionChanging)="regionChanging($event)"
placeholder="Choose Region..."
[(ngModel)]="selectedRegion"
[displayKey]="'name'"
[disabled]="regionData.length === 0">
</igx-simple-combo>
<igx-simple-combo #city
[data]="citiesData"
placeholder="Choose City..."
[(ngModel)]="selectedCity"
[displayKey]="'name'"
[disabled]="citiesData.length === 0">
</igx-simple-combo>
html
Definición de componente
export class SimpleComboCascadingComponent implements OnInit {
public selectedCountry: Country;
public selectedRegion: Region;
public selectedCity: City;
public countriesData: Country[];
public regionData: Region[] = [];
public citiesData: City[] = [];
public ngOnInit(): void {
this.countriesData = getCountries(['United States', 'Japan', 'United Kingdom']);
}
public countryChanging(e: ISimpleComboSelectionChangingEventArgs) {
this.selectedCountry = e.newSelection as Country;
this.regionData = getCitiesByCountry([this.selectedCountry?.name])
.map(c => ({name: c.region, country: c.country}))
.filter((v, i, a) => a.findIndex(r => r.name === v.name) === i);
this.selectedRegion = null;
this.selectedCity = null;
this.citiesData = [];
}
public regionChanging(e: ISimpleComboSelectionChangingEventArgs) {
this.selectedRegion = e.newSelection as Region;
this.citiesData = getCitiesByCountry([this.selectedCountry?.name])
.filter(c => c.region === this.selectedRegion?.name);
this.selectedCity = null;
}
}
typescript
Angular Enlace remoto simple de ComboBox
El componente ComboBox simple de Ignite UI for Angular expone una API que permite vincular un cuadro combinado a un servicio remoto y recuperar datos a petición.
Manifestación
El siguiente ejemplo demuestra el enlace remoto utilizando la propiedad dataPreLoad para cargar una nueva porción de datos remotos y siguiendo los pasos descritos en ComboBox Remote Binding:
Estilo
Usando el Ignite UI for Angular Theming
, podemos alterar en gran medida la apariencia del cuadro combinado simple. En primer lugar, para que podamos utilizar las funciones expuestas por el motor del tema, necesitamos importar el index
archivo en nuestro archivo de estilo:
@use 'igniteui-angular/theming' as *;
// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';
scss
Siguiendo el enfoque más simple, creamos un nuevo tema que extiende el combo-theme
y acepta el $empty-list-background
parámetro:
$custom-simple-combo-theme: combo-theme(
$empty-list-background: #1a5214
);
scss
El IgxSimpleComboComponent
utiliza internamente como un contenedor de IgxDropDownComponent
artículos. También incluye el IgxInputGroup
componente. La creación de nuevos temas, que amplían los temas de estos componentes, y el alcance de los mismos en las clases respectivas, le permitirá cambiar los estilos simples de los cuadros combinados:
$custom-drop-down-theme: drop-down-theme(
$background-color: #d9f5d6,
$header-text-color: #1a5214,
$item-text-color: #1a5214,
$focused-item-background: #72da67,
$focused-item-text-color: #1a5214,
$hover-item-background: #a0e698,
$hover-item-text-color: #1a5214,
$selected-item-background: #a0e698,
$selected-item-text-color: #1a5214,
$selected-hover-item-background: #72da67,
$selected-hover-item-text-color: #1a5214,
$selected-focus-item-background: #72da67,
$selected-focus-item-text-color: #1a5214,
);
scss
El último paso es incluir el tema del componente.
:host ::ng-deep {
@include css-vars($custom-combo-theme);
@include css-vars($custom-drop-down-theme);
}
scss
El IgxSimpleCombo
componente utiliza el IgxOverlay
servicio para contener y mostrar el contenedor de lista de elementos de cuadro combinado simple. Para definir correctamente el alcance de sus estilos, es posible que deba usar un OverlaySetting.outlet
. Para obtener más detalles, consulte el IgxOverlay Styling Guide
. También es necesario utilizarlo::ng-deep
cuando estamos peinando los componentes.
El valor predeterminado type
de the IgxSimpleCombo
es box
diferente al IgxSelect
where it is line
.
Manifestación
Problemas conocidos
- El cuadro combinado simple no tiene entrada para dimensionar su altura. En el futuro, el componente IgxInputGroup expondrá una opción que permite un tamaño personalizado y luego IgxSimpleCombo usará la misma funcionalidad para un estilo adecuado y una mejor coherencia.
- Cuando el cuadro combinado simple está vinculado a una matriz de datos primitivos que contienen
undefined
(es decir,[ undefined, ...]
),undefined
no se muestra en el menú desplegable. Cuando está vinculado a una matriz de datos complejos (es decir, objetos) y el valor utilizado paravalueKey
undefined
está definido, el elemento se mostrará en el menú desplegable, pero no se podrá seleccionar. - Cuando el cuadro combinado simple está vinculado a través de
ngModel
y está marcado comorequired
, no se pueden seleccionar los valoresnull
,undefined
y''
. - Cuando el cuadro combinado simple está vinculado a un servicio remoto y hay una selección predefinida, su entrada permanecerá en blanco hasta que se carguen los datos solicitados.
El cuadro combinado simple utiliza la directiva igxForOf
internamente, por lo que todas las limitaciones igxForOf
son válidas para el cuadro combinado simple. Para obtener más detalles, consulte la sección Problemas conocidos de igxForOf.
Resumen de API
Componentes adicionales y/o directivas con API relativas que se utilizaron:
Dependencias temáticas
Recursos adicionales
- Funciones del cuadro combinado
- Enlace remoto de ComboBox
- Plantillas de cuadros combinados
- Integración de formularios basados en plantillas
- Integración de formularios reactivos
Nuestra comunidad es activa y siempre da la bienvenida a nuevas ideas.