Descripción general del componente Angular ComboBox

El componente Angular ComboBox representa una lista desplegable que proporciona funcionalidades editables, lo que permite a los usuarios elegir múltiples opciones de una lista predefinida. La Ignite UI for Angular ComboBox también proporciona capacidades de filtrado, agrupación y adición de valores personalizados a una lista desplegable. Se puede utilizar como alternativa a la etiqueta de selección HTML y tiene varias funciones 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 Angular ComboBox, puede ver cómo los usuarios pueden filtrar elementos y realizar selecciones con los datos proporcionados. Además, ComboBox expone capacidades de navegación por teclado y 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 a la 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 ha importado la Ignite UI for Angular Combo, puede comenzar a usar el componente igx-combo.

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

Angular ComboBox Styling

Usando la Ignite UI for Angular Theming, podemos alterar en gran medida la apariencia del cuadro combinado. Primero, para que podamos utilizar las funciones expuestas por el motor de temas, necesitamos importar el archivo index 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 extiende el tema combinado y acepta el parámetro $search-separator-border-color:

$custom-combo-theme: combo-theme(
    $search-separator-border-color: #1a5214
);

IgxComboComponent utiliza IgxDropDownComponent internamente como contenedor de elementos. También incluye los componentes IgxInputGroup e IgxCheckbox. Crear nuevos temas, que amplíen los temas de estos componentes y establecer su alcance en las clases respectivas le permitirá cambiar los estilos del cuadro combinado:

$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,
);

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

El último paso es incluir el tema del componente.

:host {
    @include css-vars($custom-combo-theme);
    @include css-vars($custom-drop-down-theme);
    @include css-vars($custom-checkbox-theme);
}

Note

El componente IgxCombo utiliza el servicio IgxOverlay 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 utilizar un OverlaySetting.outlet. Para obtener más detalles, consulte la Guía de estilo de IgxOverlay.

Note

El type predeterminado de IgxCombo es box a diferencia de IgxSelect donde es line.

Demo

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.
El cuadro combinado 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 IgxCombo utilizará la misma funcionalidad para un estilo adecuado y una mejor coherencia.
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 cuadro combinado utiliza la directiva igxForOf internamente, por lo que todas las limitaciones igxForOf son válidas para el cuadro combinado. Para obtener más detalles, consulte la sección Problemas conocidos de igxForOf.

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 Angular ComboBox

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

Angular ComboBox Styling

Note

Note

Demo

Known Issues

Note

API Summary

Theming Dependencies

Additional Resources

Tematización