Lista de componentes

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.

Ejemplo de ComboBox Angular

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.

import { Component, OnInit } from '@angular/core';
import { localData } from './local-data';
import { IgxComboComponent } from 'igniteui-angular';

@Component({
    selector: 'app-combo-main',
    styleUrls: ['./combo-main.component.scss'],
    templateUrl: './combo-main.component.html',
    imports: [IgxComboComponent]
})

export class ComboMainComponent implements OnInit {
    public lData: any[];

    public ngOnInit() {
        this.lData = localData;
    }
}
ts

<igx-combo #combo class="combo" [itemsMaxHeight]="250"
    [data]="lData" [displayKey]="'field'" [valueKey]="'field'"
    placeholder="Location(s)" searchPlaceholder="Search...">
</igx-combo>
html

.combo {
    margin: 8px;
    width: 430px;
}
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 ComboBox Angular

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

Primeros pasos con 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
cmd

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

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

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

Uso del componente ComboBox Angular

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

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.

Valor de datos y propiedades de visualización

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

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.

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

export class MyCombo {
    public cities: { name: string, id: string }[] = [
                   { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...];
    public selectedCities: string[] = ['BG01', 'UK01'];
}
typescript

import { Component, ViewChild } from '@angular/core';
import { IgxComboComponent, IgxButtonDirective } from 'igniteui-angular';
import { CITIES, ICity } from './cities';
import { FormsModule } from '@angular/forms';

@Component({
    selector: 'app-combo-valuekey',
    templateUrl: 'combo-valuekey.component.html',
    styleUrls: ['combo-valuekey.component.scss'],
    imports: [IgxComboComponent, FormsModule, IgxButtonDirective]
})
export class ComboValueKeyComponent {
    @ViewChild('withValueKey', { read: IgxComboComponent })
    public comboValueKey: IgxComboComponent;

    public cities: ICity[] = CITIES;
    public selectedValueKey: string[] = ['UK01', 'BG01'];

    public selectFavorites() {
        this.comboValueKey.select(['UK01', 'BG01', 'JP01', 'DE01']);
    }
}
ts

<div class="sample-wrapper">
    <div class="combo-section">
        <igx-combo class="combo" #withValueKey [data]="cities" valueKey="id" displayKey="name" groupKey="country"
            [(ngModel)]="selectedValueKey">
        </igx-combo>
        <button igxButton="contained" (click)="selectFavorites()">Select Favorites</button>
    </div>
    <h6>Selected Cities:</h6>
    <div>{{ selectedValueKey }}</div>
</div>
html

button {
    margin: 0 8px;
}

.sample-wrapper {
    margin: 16px;
}

.combo-section {
    display: flex;
    width: 100%;
    flex-flow: row wrap;
    margin-bottom: 16px;
}

.combo {
    width: 430px;
}

@media (max-width: 700px) {
    button {
        margin: 16px 0;
    }
}
scss

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

import { Component, ViewChild } from '@angular/core';
import { IgxComboComponent, IgxButtonDirective, IgxCardComponent, IgxCardHeaderComponent, IgxCardHeaderTitleDirective, IgxCardHeaderSubtitleDirective } from 'igniteui-angular';
import { CITIES, ICity } from './cities';
import { FormsModule } from '@angular/forms';


@Component({
    selector: 'app-combo-binding',
    templateUrl: 'combo-binding.component.html',
    styleUrls: ['combo-binding.component.scss'],
    imports: [IgxComboComponent, FormsModule, IgxButtonDirective, IgxCardComponent, IgxCardHeaderComponent, IgxCardHeaderTitleDirective, IgxCardHeaderSubtitleDirective]
})
export class ComboBindingComponent {
    @ViewChild('noValueKey', { read: IgxComboComponent })
    public comboNoValueKey: IgxComboComponent;

    public cities: ICity[] = CITIES;
    public selectedNoValueKey: ICity[] = [this.cities[4], this.cities[0]];

    public selectFavorites() {
        const selectedItems: ICity[] = this.cities.filter((e: ICity) => ['UK01', 'BG01', 'JP01', 'DE01'].indexOf(e.id) > -1);
        this.comboNoValueKey.select(selectedItems);
    }
}
ts

<div class="sample-wrapper">
  <div class="combo-section">
    <igx-combo class="combo" #noValueKey [data]="cities" displayKey="name"
      groupKey="country" [(ngModel)]="selectedNoValueKey">
    </igx-combo>
    <button igxButton="contained" (click)="selectFavorites()">Select Favorites</button>
  </div>
  <h6>Selected Cities:</h6>
  <div class="cities-container">
    @for (city of selectedNoValueKey; track city) {
      <igx-card >
        <igx-card-header>
          <h5 igxCardHeaderTitle>{{ city.name }}</h5>
          <h5 igxCardHeaderSubtitle>{{ city.country }}</h5>
          {{ city.id }}
        </igx-card-header>
      </igx-card>
    }
  </div>
</div>

html

button {
    margin: 0 8px;
}

.sample-wrapper {
    margin: 16px;
    max-height: 600px;
}

.combo-section {
    display: flex;
    justify-content: space-between;
    max-width: 630px;
    flex-flow: row wrap;
    margin-bottom: 16px;
}

.combo {
    width: 430px;
}

.cities-container {
    max-width: 630px;
    max-height: 450px;
    overflow-y: auto;

    igx-card {
        margin: 8px 8px 8px 0;
    }
}

@media (max-width: 700px) {
    button {
        margin: 16px 0;
    }
}
scss

API de selección

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

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

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

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

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

Selección única

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

public singleSelection(event: IComboSelectionChangeEventArgs) {
    if (event.added.length) {
        event.newValue = event.added;
    }
}
typescript

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.

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.

Estilo

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';
scss

Siguiendo el enfoque más simple, creamos un nuevo tema que extiende el combo-theme y acepta el $search-separator-border-color parámetro:

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

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: #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,
);
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);
  @include css-vars($custom-checkbox-theme);
}
scss

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.

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

Manifestación

import { Component, ElementRef, OnInit, ViewChild } from '@angular/core';
import { IComboSelectionChangingEventArgs, IgxToastComponent, VerticalAlignment, IgxComboComponent } from 'igniteui-angular';
import { getHeroWeaponsData, IHeroWeapon } from '../../../data/heroData';

@Component({
    selector: 'app-combo',
    styleUrls: ['./combo-styling.component.scss'],
    templateUrl: './combo-styling.component.html',
    imports: [IgxComboComponent, IgxToastComponent]
})
export class ComboStylingComponent implements OnInit {
    @ViewChild('loadToast', { read: IgxToastComponent, static: true })
    public loadToast: IgxToastComponent;

    public weaponsData: IHeroWeapon[] = [];

    constructor(public elem: ElementRef) {
    }

    public ngOnInit() {
        this.weaponsData = getHeroWeaponsData();
    }

    public setWeaponsLimit(event: IComboSelectionChangingEventArgs) {
        this.loadToast.positionSettings.verticalDirection = VerticalAlignment.Middle;
        // this.loadToast.autoHide = true;

        if (event.newValue.length > 2) {
            event.cancel = true;
            this.loadToast.open('Choose only two items');
        }
    }
}
ts

<div class="control-wrapper">
    <igx-combo [width]="'430px'" [data]="weaponsData" [displayKey]="'field'" [valueKey]="'field'" [overlaySettings]="{outlet: elem}"
        [groupKey]="'weaponRange'" placeholder="Pick up two weapons" searchPlaceholder="Search..."
        [itemsMaxHeight]="255" (selectionChanging)="setWeaponsLimit($event)">
    </igx-combo>

    <igx-toast #loadToast [displayTime]="1200"></igx-toast>
</div>


html

@use "layout.scss";
@use "igniteui-angular/theming" as *;

$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-combo-theme: combo-theme(
  $search-separator-border-color: #1a5214
);

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

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

Problemas conocidos

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.

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.

Resumen de API

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