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.

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

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

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

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

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

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

// home.component.ts

import { IGX_SIMPLE_COMBO_DIRECTIVES } from 'igniteui-angular/simple-combo';
// 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 tienes importado el módulo o directivas Ignite UI for Angular Simple ComboBox, puedes empezar a usar eligx-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);
    }
}

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

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

Valor de datos y propiedades de visualización

Dado que la caja combobox simple 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 simple de la combobox. SivalueKey se omite, el valor simple de combobox usará referencias a las entradas de datos (es decir, la selección será un array de entradas de).igxSimpleCombo.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 simple usará el especificadovalueKey (si es que lo hay).

En nuestro caso, queremos que la caja combobox simple muestre elname de cada ciudad y su valor para almacenar elid de cada ciudad. Por lo tanto, estamos vinculando estas propiedades como valores a las comboboxesdisplayKey simples yvalueKey, respectivamente:

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

Nota

Cuando la fuente de datos está compuesta por un tipo simple (por ejemplostring[],),number[]​ ​no especifique unvalueKey ydisplayKey.

Encuadernación bidireccional

El componente combobox simple soporta completamente la vinculación de datos bidireccional,[(ngModel)] así como su uso en formas basadas en plantillas y reactivas. La simple selección de combobox puede accederse tanto mediante binding bidireccional como mediante la API de selección. Podemos pasar un objeto del mismo tipo que los que están en la selección de la caja combobox simple (en función de)valueKey y cada vez que uno cambia, el otro se actualiza en consecuencia.

En el siguiente ejemplo, se seleccionará inicialmente la primera ciudad de los datos proporcionados. Cualquier cambio adicional en la selección de la caja combobox simple se reflejará en elselectedCities.

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

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

export class MySimpleComboComponent {
    public cities: City[] = [
                   { name: 'Sofia', id: '1' }, { name: 'London', id: '2' }, ...];
    public selectedCity: City = this.cities[0];
}

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á laid 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 pulsa el botón,London se añadirá a la selección del combobox 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 puede hacerse mediante la propiedad adecuada@Output en laigx-simple-combo etiqueta:

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

Navegación por teclado

Cuando el cuadro combinado simple está cerrado y enfocado:

• ArrowDownoAlt +ArrowDown abrirá el desplegable del combobox simple.

Nota

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:

• 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 mientras seleccionas todo el texto de la entrada.

• Endpasaré al último elemento de la lista.

• Homepasaré al primer elemento de la lista.

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

• Enterseleccionará/deseleccionará el elemento de la lista activa y cerrará la lista.

• Esccerraré la lista.

Cuando se abre el cuadro combinado simple y 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.

• ArrowUpmoverá el foco de nuevo 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>

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

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:

Estilismo

Con estoIgnite UI for Angular Theming, podemos alterar mucho la apariencia simple 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 extiende elcombo-theme y acepta el$empty-list-background parámetro:

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

UtilizaIgxSimpleComboComponent elIgxDropDownComponent interior como contenedor de objetos. También incluye elIgxInputGroup componente. Crear nuevos temas que amplíen los temas de estos componentes y ubicarlos bajo las respectivas clases te permitirá cambiar los estilos simples de combobox:

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

Nota

ElIgxSimpleCombo componente utiliza elIgxOverlay servicio para almacenar y mostrar el contenedor de lista de elementos del combobox sencillo. 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.

Nota

El valor por defectotype de laIgxSimpleCombo esbox diferente alIgxSelect donde está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 la caja combobox simple está vinculada 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 la caja combobox simple está asignada mediantengModel y se marca comorequired,null,undefined y'' no se pueden seleccionar valores.
• 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.

Nota

La combobox simple usaigxForOf directiva internamente, por lo que todasigxForOf las limitaciones son válidas para la combobox simple. Para más detalles, véase la sección de Problemas Conocidos de igxForOf.

Resumen de API

• Componente IgxSimpleCombo
• Estilos de componentes IgxCombo

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

• Componente IgxDropDown
• Componente IgxInputGroup

Dependencias temáticas

• Tema desplegable Igx
• Tema IgxIcon
• Tema IgxOverlay

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.

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