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 importar IgxComboModule en su archivo app.module.ts.

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

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

Alternativamente, a partir de 16.0.0, puede importar IgxComboComponent como una dependencia independiente o usar el token IGX_COMBO_DIRECTIVES para importar el componente y todos sus componentes y directivas de soporte.

// home.component.ts

import { IGX_COMBO_DIRECTIVES } from 'igniteui-angular';
// 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 tiene el módulo o las directivas Ignite UI for Angular Combo importados, puede comenzar a usar el igx-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 el cuadro combinado 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. Si se omite valueKey, el valor del cuadro combinado utilizará referencias a las entradas de datos (es decir, la selección será una matriz de entradas de igxCombo.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 para displayKey, el cuadro combinado utilizará la valueKey especificada (si corresponde).

En nuestro caso, queremos que el cuadro combinado muestre el name de cada ciudad y el valor del cuadro combinado para almacenar la id de cada ciudad. Por lo tanto, proporcionamos estas propiedades a displayKey y valueKey del cuadro combinado, respectivamente:

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

Note

Cuando la fuente de datos es una matriz de primitivas (por ejemplo, string[], number[]), no especifique valueKey y displayKey. Se utilizarán valores primitivos tanto para el valor como para el texto.

Encuadernación bidireccional

El componente de cuadro combinado 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 mediante enlace bidireccional o mediante la API de selección. Podemos pasar una serie de elementos del mismo tipo que los de la selección del cuadro combinado (según valueKey) y cada vez que uno cambia, el otro se actualiza en consecuencia.

En el siguiente ejemplo, inicialmente se seleccionarán las ciudades Sofía y Londres. Cualquier cambio adicional en la selección del cuadro combinado se reflejará en la matriz selectedCities.

<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'];
}

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 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 los id de las ciudades 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 se puede realizar a través de la propiedad @Output adecuada en la etiqueta igx-combo:

<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

De forma predeterminada, el control combinado proporciona selección múltiple. El siguiente fragmento demuestra cómo lograr una selección única en el componente adjuntando un controlador al evento selectionChanging:

<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.

Cuando el cuadro combinado está cerrado y enfocado:

ArrowDown o Alt + ArrowDown abrirán el menú desplegable del cuadro combinado y moverán el foco a la entrada de búsqueda.

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

ArrowUp o Alt + ArrowUp cerrarán el menú desplegable del cuadro combinado y moverán el foco al cuadro combinado cerrado.
ArrowDown moverá el foco de la entrada de búsqueda al primer elemento de la lista. Si la lista está vacía y los valores personalizados están habilitados, la moverá al botón Agregar 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:

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.
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 confirmará los elementos ya seleccionados y cerrará la lista.
Esc cerrará la lista.

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

Enter agregará un nuevo elemento con valueKey y displayKey igual al texto en la entrada de búsqueda y seleccionará el nuevo elemento.
El foco ArrowUp volverá al último elemento de la lista o, si la lista está vacía, se moverá 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.

Usando el Ignite UI for Angular Theming, podemos alterar en gran medida la apariencia del cuadro combinado. 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';

Siguiendo el enfoque más simple, creamos un nuevo tema que amplía el combo-theme. Al establecer el $toggle-button-background, el tema determina automáticamente los colores de estado adecuados y los primeros planos de contraste para el botón. También puede especificar parámetros adicionales, como $search-separator-border-color:

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

El IgxComboComponent utiliza internamente como un contenedor de IgxDropDownComponent artículos. También incluye el IgxInputGroup y los IgxCheckbox componentes. 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 de los cuadros combinados:

$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

El IgxCombo componente utiliza el IgxOverlay servicio para contener y mostrar el contenedor de la lista de elementos del cuadro combinado. 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.

Note

El valor predeterminado type de the IgxCombo es box diferente al IgxSelect where it is line.

Demo

Styling with Tailwind

Puedes decorarlos combo 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 de light ambos temas dark.

Usa light-* clases para el tema de la luz.
Usa dark-* 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 de temas dinámicos. A partir de ahí, puede anular las variables CSS generadas usando arbitrary properties. Después de los dos puntos, proporcione 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 garantizar 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 cuadro combinado 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 para valueKey undefined está definido, el elemento se mostrará en el menú desplegable, pero no se podrá seleccionar.
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

El combobox usa igxForOf la directiva internamente, por lo tanto, todas las igxForOf limitaciones son válidas para el combobox. Para obtener más detalles, consulte igxForOf Known Issues la sección.

API Summary

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

Theming Dependencies

Additional Resources

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

Descripción general del componente ComboBox Angular

Angular ComboBox Example

Angular ComboBox Features

Getting Started with Ignite UI for Angular ComboBox

Using the Angular ComboBox Component

Data value and display properties

Note

Encuadernación bidireccional

Selection API

Single Selection

Keyboard Navigation

Note

Estilismo

Combo Theme Property Map

Note

Note

Demo

Styling with Tailwind

Note

Known Issues

Note

API Summary

Theming Dependencies

Additional Resources

Tematización