Descripción general del componente ComboBox Angular

El componente ComboBox Angular representa una lista desplegable que proporciona funcionalidades editables, lo que permite a los usuarios elegir varias opciones de una lista predefinida. El componente ComboBox Ignite UI for Angular también proporciona capacidades de filtrado, agrupación y adición de valores personalizados a una lista desplegable. Se puede usar como alternativa a la etiqueta de selección HTML y tiene varias características listas para usar, como enlace de datos (local y remoto), filtrado, agrupación, plantillas personalizadas para elementos, encabezado y pie de página, valores personalizados y más.

Angular ComboBox Example

En este ejemplo de ComboBox Angular, puede ver cómo los usuarios pueden filtrar elementos y realizar selecciones con los datos proporcionados. Además, ComboBox muestra navegación mediante teclado y capacidades de estilo personalizado.

Angular ComboBox Features

El control de cuadro combinado expone las siguientes características:

• Enlace de datos: datos locales y datos remotos
• Enlace de valor
• Filtración
• Agrupamiento
• Valores personalizados
• Plantillas
• Integración con formularios basados en plantillas y formularios reactivos

Getting Started with Ignite UI for Angular ComboBox

Para comenzar con el componente Ignite UI for Angular ComboBox, primero debe instalar Ignite UI for Angular. En una aplicación Angular existente, escriba el siguiente comando:

ng add igniteui-angular

Para obtener una introducción completa al Ignite UI for Angular, lea el tema de introducción.

El siguiente paso es importarlosIgxComboModule en tu archivo app.module.ts.

import { IgxComboModule } from 'igniteui-angular/combo';
// import { IgxComboModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    imports: [
        ...
        IgxComboModule,
        ...
    ]
})
export class AppModule {}

Alternativamente,16.0.0 puedes importarlosIgxComboComponent como una dependencia independiente, o usar elIGX_COMBO_DIRECTIVES token para importar el componente y todos sus componentes y directivas de soporte.

// home.component.ts

import { IGX_COMBO_DIRECTIVES } from 'igniteui-angular/combo';
// import { IGX_COMBO_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: '<igx-combo></igx-combo>',
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [IGX_COMBO_DIRECTIVES]
    /* or imports: [IgxComboComponent] */
})
export class HomeComponent {}

Ahora que tienes importado el módulo o directivas Ignite UI for Angular Combo, puedes empezar a usar eligx-combo componente.

Using the Angular ComboBox Component

Después de la configuración inicial, puede vincular el igx-combo a los datos.

@Component({
    selector: 'app-combo-demo',
    template: '<igx-combo [data]="cities"></igx-combo>',
    styleUrls: ['combo-demo.component.scss'],
    standalone: true,
    imports: [IGX_COMBO_DIRECTIVES]
})
export class ComboDemo implements OnInit {
    public cities: { name: string, id: string }[] = [];

    public ngOnInit() {
        this.cities = [{ name: 'London', id: 'UK01' }, { name: 'Sofia', id: 'BG01'}, ...];
    }
}

Nuestro cuadro combinado ahora está vinculado al conjunto de ciudades, pero todavía no le hemos dicho al componente qué propiedad usar para el texto de los elementos y cuál usar para el valor. Hagámoslo ahora.

Data value and display properties

Dado que la caja combobox está vinculada a un array de datos complejos (es decir, objetos), necesitamos especificar una propiedad que el control usará para manejar los elementos seleccionados. El control expone dos@Input propiedades: valueKey y displayKey:

• valueKey-Opcional, recomendado para arrays de objetos- Especifica qué propiedad de las entradas de datos se almacenarán para la selección del combobox. SivalueKey se omite, el valor de combobox usará referencias a las entradas de datos (es decir, la selección será un array de entradas de).igxCombo.data​
• displayKey-Requerida para arrays de objetos- Especifica qué propiedad se usará para el texto de los elementos. Si no se especifica ningún valordisplayKey, la caja combobox usará el especificadovalueKey (si es que lo hay).

En nuestro caso, queremos que la caja combobox muestre elname valor de cada ciudad y el valor del combobox para almacenar elid de cada ciudad. Por lo tanto, estamos proporcionando estas propiedades a las comboboxesdisplayKey yvalueKey, respectivamente:

<igx-combo [data]="cities" displayKey="name" valueKey="id"></igx-combo>

Note

Cuando la fuente de datos es un array de primitivas (por ejemplostring[],),number[]​ ​no especifique unvalueKey ydisplayKey. Se usarán valores primitivos tanto para valor como para texto.

Encuadernación bidireccional

El componente combobox soporta completamente la vinculación de datos bidireccional con[(ngModel)] y su uso en formas basadas en plantillas y reactivas. La selección de combobox puede accederse mediante binding bidireccional o mediante la API de selección. Podemos pasar una matriz de elementos del mismo tipo que los que está en la selección del combobox (en función devalueKey) y cada vez que uno cambia, el otro se actualiza en consecuencia.

En el siguiente ejemplo, inicialmente se seleccionarán las ciudades de Sofía y Londres. Cualquier cambio adicional en la selección de la caja combinada se reflejará en elselectedCities array.

<igx-combo [data]="cities" [(ngModel)]="selectedCities" displayKey="name" valueKey="id"></igx-combo>

export class MyCombo {
    public cities: { name: string, id: string }[] = [
                   { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...];
    public selectedCities: string[] = ['BG01', 'UK01'];
}

La unión bidireccional también puede lograrse sin especificarvalueKey nada. Por ejemplo, sivalueKey se omite, el modelo acotado se verá así:

export class MyCombo {
    public cities: { name: string, id: string } [] = [
                   { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...];
    public selectedCities: { name: string, id: string } [] = [this.cities[0], this.cities[1]];
}

Selection API

El componente del cuadro combinado expone una API que permite obtener y manipular el estado de selección actual del control.

Una forma de obtener la selección del cuadro combinado es mediante la propiedad de selección. Devuelve una matriz de valores que corresponden a los elementos seleccionados, según la clave de valor especificada (si corresponde).

En nuestro ejemplo,selection devolverá una matriz de las ciudadesid seleccionadas:

export class MyCombo {
    ...
    public selection: string[] = this.combo.selection;
}

Usando la API de selección, también puede cambiar los elementos seleccionados del cuadro combinado 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 seleccione un conjunto de ciudades, usando el método select():

<igx-combo [data]="cities" displayKey="name" valueKey="id"></igx-combo>
<button igxButton (click)="selectFavorites()">Select Favorites</button>

Al hacer clic en el botón, las ciudades Londres y Sofía se agregarán a la selección del cuadro combinado:

export class MyExampleCombo {
    @ViewChild(IgxComboComponent, { read: IgxComboComponent, static: true })
    public combo: IgxComboComponent;
    ...
    selectFavorites(): void {
        this.combo.select(['UK01', 'BG01']);
    }
}

El cuadro combinado también activa un evento cada vez que cambia su selección: selecciónChanging(). Los argumentos del evento emitido, IComboSelectionChangingEventArgs, contienen información sobre la selección anterior al cambio, la selección actual y los elementos que se agregaron o eliminaron. El evento también se puede cancelar, impidiendo la actualización de la selección con la nueva matriz de elementos.

La vinculación al evento puede hacerse mediante la propiedad adecuada@Output en laigx-combo etiqueta:

<igx-combo [data]="cities" displayKey="name" valueKey="id"
           (selectionChanging)="handleCityChange($event)">
</igx-combo>

En el siguiente ejemplo, cuando se agrega o elimina una ciudad de la selección, se activa un controlador que actualiza la visualización de estadísticas:

export class MyExampleCombo {
    ...
    handleCityChange(event: IComboSelectionChangeEventArgs): void {
        for (const item of event.added) {
            this.addToVisualization(item);
        }
        for (const item of event.removed) {
            this.removeFromVisualization(item);
        }
    }
}

Single Selection

Por defecto, el control de combo ofrece selección múltiple. El fragmento siguiente demuestra cómo lograr una sola selección en el componente adjuntando un manejador alselectionChanging evento:

<igx-combo [data]="lData" (selectionChanging)="singleSelection($event)"></igx-combo>

public singleSelection(event: IComboSelectionChangeEventArgs) {
    if (event.added.length) {
        event.newValue = event.added;
    }
}

Nota: Se recomienda utilizar igxSimpleCombo en lugar de modificar igxCombo como se muestra arriba.

Keyboard Navigation

Cuando el cuadro combinado está cerrado y enfocado:

• ArrowDownoAlt +ArrowDown abrirá el desplegable del combobox y moverá el enfoque a la entrada de búsqueda.

Cuando se abre el cuadro combinado y la entrada de búsqueda está enfocada:

• ArrowUpoAlt +ArrowUp cerrará el desplegable del combobox y moverá el foco al combo cerrado.

• ArrowDownMoverá el enfoque de la entrada de búsqueda al primer elemento de la lista. Si la lista está vacía y los valores personalizados están activados, se moverá al botón Añadir nuevo elemento.

Note

Cualquier otra pulsación de tecla será manejada por la entrada.

Cuando se abre el cuadro combinado y el elemento de la lista está enfocado:

• ArrowDownpasaré al siguiente elemento de la lista. Si el elemento activo es el último de la lista y los valores personalizados están activados, el foco se trasladará al botón Añadir objeto.

• ArrowUppasaré al elemento anterior de la lista. Si el elemento activo es el primero de la lista, el foco volverá a la entrada de búsqueda.

• Endpasaré al último elemento de la lista.

• Homepasaré al primer elemento de la lista.

• Spaceseleccionarán/desseleccionarán el elemento de la lista activa.

• EnterConfirmará los elementos ya seleccionados y cerrará la lista.

• Esccerraré la lista.

Cuando se abre el cuadro combinado, se habilitan los valores personalizados y el botón Agregar elemento está enfocado:

• EnterAñadirá un nuevo elemento igualvalueKey​displayKey al texto en la entrada de búsqueda y seleccionará el nuevo elemento.

• ArrowUpEl foco volverá a moverse al último elemento de la lista o, si la lista está vacía, se trasladará a la entrada de búsqueda.

Estilismo

Combo Theme Property Map

Cuando modificas una propiedad primaria, todas las propiedades dependientes relacionadas se actualizan automáticamente:

Propiedad principal	Propiedad dependiente	Descripción
$empty-lista de antecedentes	$empty-lista-placeholder-color	El color de texto provisional combinado.
$toggle-fondo de botones	$toggle-botón en primer plano	El botón de combo activa el color del primer plano.
	$toggle-botón-fondo-enfoque	El botón de combo activa el color de fondo cuando está enfocado.
	$toggle-botón-fondo-enfoque--borde	El botón de interruptor activa el color de fondo cuando se enfoca (variante de borde).
	$toggle-lleno de botones en primer plano	El botón de interruptor de combo cambia el color del primer plano cuando está lleno.
	$toggle-botón-fondo-desactivado	El botón combo activa el color de fondo cuando está desactivado.
	$toggle-botón-primer plano-desactivado	El botón de combo activa el color del primer plano cuando está desactivado.
$toggle-botón-fondo-enfoque	$toggle-botón-primer plano-enfoque	El botón de interruptor de combo activa el color del primer plano cuando está enfocado.
$clear-botón-fondo-enfoque	$clear-botón-primer plano	El botón de combo para limpiar el color del primer plano cuando está enfocado.

Con estoIgnite UI for Angular Theming, podemos alterar mucho la apariencia de las combobox. Primero, para que podamos usar las funciones expuestas por el motor de temas, necesitamos importar elindex 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';

Siguiendo el enfoque más sencillo, creamos un nuevo tema que amplía elcombo-theme. Al configurar el$toggle-button-background, el tema determina automáticamente los colores de estado adecuados y el contraste en primer plano para el botón. También puedes especificar parámetros adicionales, como$search-separator-border-color:

$custom-combo-theme: combo-theme(
  $search-separator-border-color: #1d3743,
  $toggle-button-background: #57a5cd,
);

UtilizaIgxComboComponent elIgxDropDownComponent interior como contenedor de objetos. También incluye losIgxInputGroup componentes yIgxCheckbox los componentes. Crear nuevos temas que amplíen los temas de estos componentes y asignarlos a las clases respectivas te permitirá cambiar los estilos de combobox:

$custom-drop-down-theme: drop-down-theme(
  $background-color: #57a5cd,
);

$custom-checkbox-theme: checkbox-theme(
  $border-radius: 10px,
  $fill-color: #1d3743,
  $empty-color: #1d3743,
);

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);
  @include css-vars($custom-checkbox-theme);
}

Note

ElIgxCombo componente utiliza elIgxOverlay servicio para almacenar y mostrar el contenedor de la lista de elementos combobox. Para definir correctamente tus estilos puede que tengas que usar unOverlaySetting.outlet. Para más detalles, consulta elIgxOverlay Styling Guide. También es necesario usarlos::ng-deep cuando estilizamos los componentes.

Note

El valor por defectotype de laIgxCombo esbox diferente alIgxSelect donde estáline.

Demo

Styling with Tailwind

Puedes decorarloscombo usando nuestras clases utilitarias personalizadas de Tailwind. Asegúrate de configurar primero a Tailwind.

Junto con la importación de viento de cola en su hoja de estilo global, puede aplicar las utilidades de tema deseadas de la siguiente manera:

@import "tailwindcss";
...
@use 'igniteui-theming/tailwind/utilities/material.css';

El archivo de utilidad incluye variantes tantolight comodark de tema.

• Usalight-* clases para el tema ligero.
• Usadark-* clases para el tema oscuro.
• Añadir el nombre del componente después del prefijo, por ejemplo, ,light-combo,dark-combo.

Una vez aplicadas, estas clases permiten cálculos dinámicos de temas. Desde ahí, puedes anular las variables CSS generadas usandoarbitrary properties. Después de los dos puntos, proporciona cualquier formato de color CSS válido (HEX, variable CSS, RGB, etc.).

Puedes encontrar la lista completa de propiedades en el tema combinado. La sintaxis es la siguiente:

<igx-combo
class="!light-combo
![--toggle-button-background:#99BAA6]
![--clear-button-foreground:#99BAA6]"
...></igx-combo>

Note

El signo de exclamación(!) es necesario para asegurar que la clase de utilidad tenga prioridad. Tailwind aplica estilos en capas y, sin marcar estos estilos como importantes, serán anulados por el tema predeterminado del componente.

Al final tu combo debería verse así:

Known Issues

• La entrada del cuadro combinado que muestra los elementos seleccionados no es editable. Sin embargo, debido a las características específicas del navegador Firefox, el cursor está visible.
• Cuando el combobox está vinculado a un array de datos primitivos que contieneundefined (es decir[ undefined, ...]),undefined no se muestra en el desplegable. Cuando está vinculado a un array de datos complejos (es decir, objetos) y el valor usado paravalueKey esundefined, el elemento se mostrará en el desplegable, pero no podrá seleccionarse.
• Cuando el combobox está vinculado a un servicio remoto y hay una selección predefinida, su entrada permanecerá en blanco hasta que se carguen los datos solicitados.

Note

La combobox usaigxForOf directiva internamente, por lo que todasigxForOf las limitaciones son válidas para la combobox. Para más detalles, véaseigxForOf Known Issues la sección.

API Summary

• Componente IgxCombo
• Estilos de componentes IgxCombo

​Componentes angulares adicionales y/o directivas con API relativas que se utilizaron:

• Componente IgxDropDown
• Componente IgxInputGroup
• Componente IgxCheckbox

Theming Dependencies

• Tema desplegable Igx
• Tema IgxIcon
• Tema IgxCheckbox
• Tema IgxOverlay

Additional Resources

• Funciones del cuadro combinado
• Enlace remoto de ComboBox
• Plantillas de cuadros combinados
• Integración de formularios basados en plantillas
• Integración de formularios reactivos
• Cuadro combinado de selección única

Nuestra comunidad es activa y siempre da la bienvenida a nuevas ideas.

• Ignite UI for Angular Foros
• Ignite UI for Angular GitHub