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.

    EXAMPLE
    TS
    HTML
    SCSS

    ¿Te gusta esta muestra? Obtenga acceso a nuestro kit de herramientas de Ignite UI for Angular completo y comience a crear sus propias aplicaciones en minutos. Descárgalo gratis.

    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
    cmd

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

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

    Ahora que tiene el módulo o las directivas Ignite UI for Angular Simple ComboBox importados, puede comenzar a usar el igx-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);
        }
    }
    typescript
    <igx-simple-combo [data]="cities"></igx-simple-combo>
    html

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

    Valor de datos y propiedades de visualización

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

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

    Enlace 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>
    html
    export class MySimpleComboComponent implements OnInit {
        public cities: City[];
        public selectedCity: number;
    
        public ngOnInit(): void {
            this.cities = getCitiesByPopulation(10000000);
            this.selectedCity = this.cities[0].id;
        }
    }
    typescript

    EXAMPLE

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

    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á la id de la ciudad seleccionada:

    export class MySimpleComboComponent {
        ...
        public selection: string = this.simpleCombo.selection;
    }
    typescript

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

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

    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>
    html
    App Builder | CTA Banner

    Navegación por teclado

    Cuando el cuadro combinado simple está cerrado y enfocado:

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

    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.

    Escenario en cascada

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

    EXAMPLE

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

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

    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:

    EXAMPLE
    TS
    HTML
    SCSS

    Estilo

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

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

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

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

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

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

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

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

    Manifestación

    EXAMPLE

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

    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.

    Resumen de API

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

    Dependencias temáticas

    Recursos adicionales

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