Descripción general del componente ComboBox de selección única Angular

El componente Angular Single Select ComboBox es una modificación del componente ComboBox que permite una selección única. Lo llamamos "combo simple". Debido a la gran 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.

Angular Simple ComboBox Example

En este ejemplo Angular Simple ComboBox, puede ver cómo los usuarios pueden seleccionar el tipo de línea de tendencia del gráfico. Además, Simple ComboBox expone la navegación con el teclado y capacidades de estilo personalizado.

Angular Simple ComboBox Features

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

Getting Started with Ignite UI for Angular Simple ComboBox

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

Para obtener una introducción completa a la 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 {}

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 {}

Ahora que tiene importadas las directivas o el módulo Ignite UI for Angular Simple ComboBox, puede comenzar a usar el componente igx-simple-combo.

Using the Angular Simple ComboBox

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);
    }
}

<igx-simple-combo [data]="cities"></igx-simple-combo>

Nuestro cuadro combinado simple ahora está vinculado a la variedad de ciudades.

Data value and display properties

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 omite valueKey, el valor del cuadro combinado simple utilizará referencias a las entradas de datos (es decir, la selección será una matriz de entradas de igxSimpleCombo.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 simple utilizará la valueKey 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>

Note

Cuando la fuente de datos se compone de un tipo simple (por ejemplo, string[], number[]), no especifique valueKey y displayKey.

Encuadernación 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>

export class MySimpleComboComponent implements OnInit {
    public cities: City[];
    public selectedCity: number;

    public ngOnInit(): void {
        this.cities = getCitiesByPopulation(10000000);
        this.selectedCity = this.cities[0].id;
    }
}

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

Selection API

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

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>

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

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>

Keyboard Navigation

Cuando el cuadro combinado simple está cerrado y enfocado:

• ArrowDown o Alt + ArrowDown abrirán el menú desplegable del cuadro combinado simple.

Note

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 con valueKey y displayKey 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.

Cascading Scenario

El siguiente ejemplo demuestra un escenario en el que se utiliza el combo igx-simple:

Consulte nuestro ejemplo de cuadrícula Angular con combinaciones en cascada.

Template Configuration

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>

Component Definition

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

Angular Simple ComboBox Remote Binding

La Ignite UI for Angular Simple ComboBox expone una API que permite vincular un cuadro combinado a un servicio remoto y recuperar datos a pedido.

Demo

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:

Angular Simple ComboBox Styling

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

Siguiendo el enfoque más simple, creamos un nuevo tema que extiende el tema combinado y acepta el parámetro $empty-list-background:

$custom-simple-combo-theme: combo-theme(
    $empty-list-background: #1a5214
);

​IgxSimpleComboComponent utiliza IgxDropDownComponent internamente como contenedor de elementos. También incluye el componente IgxInputGroup. Crear nuevos temas, que amplíen los temas de estos componentes y asignarles su alcance en las clases respectivas, le permitirá cambiar los estilos simples 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,
);

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);
}

Note

El componente IgxSimpleCombo utiliza el servicio IgxOverlay para contener y mostrar el contenedor de lista de elementos del cuadro combinado simple. 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 IgxSimpleCombo es box a diferencia de IgxSelect donde es line.

Demo

Known Issues

• 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 para valueKey​ ​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 como required, no se pueden seleccionar los valores null, 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.

Note

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.

API Summary

• Componente IgxSimpleCombo
• Estilos de componentes IgxCombo

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

• Componente IgxDropDown
• Componente IgxInputGroup

Theming Dependencies

• Tema desplegable Igx
• Tema IgxIcon
• 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

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

• Ignite UI for Angular foros angulares
• Ignite UI for Angular GitHub