Descripción general del cuadro combinado Web Components

    Web Components ComboBox es un editor liviano que permite a los usuarios seleccionar, filtrar y agrupar fácilmente diferentes opciones predefinidas en una lista proporcionada. El componente también admite opciones para la navegación con el teclado ComboBox Web Components y plantillas para personalizar cómo se muestran los elementos, el encabezado y el pie de página.

    El componente ComboBox Ignite UI for Web Components proporciona una lista de opciones entre las que los usuarios pueden realizar una selección. Muestra todas las opciones en una lista virtualizada de elementos, lo que significa que ComboBox puede mostrar simultáneamente miles de registros, donde se pueden seleccionar una o más opciones. Además, el componente presenta filtrado, agrupación, enlace de datos complejos que distingue entre mayúsculas y minúsculas y más.

    Web Components ComboBox Example

    Getting Started with Web Components ComboBox

    Primero, debe instalar la Ignite UI for Web Components ejecutando el siguiente comando:

    npm install igniteui-webcomponents

    Antes de usar el componente, debe registrarlo junto con sus componentes adicionales y el ComboBox CSS necesario:

    import { defineComponents, IgcComboComponent }
from 'igniteui-webcomponents';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

defineComponents(IgcComboComponent);

    Para obtener una introducción completa a Ignite UI for Web Components, lea el tema Introducción.

    [!WARNING] The IgcComboComponent component doesn't work with the standard <form> element. Use IgcFormComponent instead.

    Luego, vincularemos una serie de objetos a la fuente de datos combinada utilizada para crear la lista de opciones.

    interface City {
    id: string;
    name: string;
}

const cities: City[] = [
    { name: 'London', id: 'UK01' },
    { name: 'Sofia', id: 'BG01'},
    { name: 'New York', id: 'NY01'}
];

export class Sample {
    private combo: IgcComboComponent<City>;

    constructor() {
        this.combo = document.getElementById('basic-combo') as IgcComboComponent<City>;
        this.combo.data = cities;
    }
}

    <igc-combo id='basic-combo' display-key='name' value-key='id' value='["BG01"]'></igc-combo>

    Data value and display properties

    Cuando el combo está vinculado a una lista de datos complejos (es decir, objetos), necesitamos especificar una propiedad que el control utilizará para manejar la selección de elementos. El componente expone las siguientes propiedades:

    • valueKey: opcional, necesario para objetos de datos complejos: determina qué campo de la fuente de datos se utilizará para realizar selecciones. Si se omite valueKey, la API de selección utilizará referencias de objetos para seleccionar elementos.
    • displayKey: opcional, recomendado para objetos de datos complejos: determina qué campo de la fuente de datos se utiliza como valor de visualización. Si no se especifica ningún valor para displayKey, el combo utilizará la valueKey especificada (si corresponde). En nuestro caso, queremos que el combo muestre el name de cada ciudad y use el campo id para la selección de elementos y como valor subyacente para cada elemento. Por lo tanto, proporcionamos estas propiedades a valueKey y displayKey del combo respectivamente.

    [!Note] When the data source consists of primitive types (e.g. strings, numbers, etc.), do not specify a valueKey and/or displayKey.

    Setting Value

    El componente ComboBox expone un captador y definidor value además de un atributo, que también se denomina valor. Puede utilizar el atributo de valor para configurar los elementos seleccionados en la inicialización del componente.

    Si desea leer el valor, es decir, la lista de elementos seleccionados actualmente, o actualizar el valor, utilice el captador y definidor de valores respectivamente. El captador de valores devolverá una lista de todos los elementos seleccionados representados por valueKey. Del mismo modo, si desea actualizar la lista de elementos seleccionados utilizando el definidor de valores, debe proporcionar una lista de elementos por su valueKey.

    Example:

    const combo = document.getElementById('basic-combo') as IgcComboComponent<City>;

// Given the overview example from above this will return ['BG01']
console.log(combo.value);

// Change the selected items to New York and London
combo.value = ['NY01', 'UK01'];

    Selection API

    El componente combinado expone API que le permiten cambiar los elementos seleccionados actualmente.

    Además de seleccionar elementos de la lista de opciones mediante la interacción del usuario, puede seleccionar elementos mediante programación. Esto se hace mediante los métodos select y deselect. Puede pasar una variedad de elementos a ambos métodos. Si los métodos se llaman sin argumentos, todos los elementos se seleccionarán/deseleccionarán dependiendo del método que se llame. Si ha especificado una valueKey para su componente combinado, entonces debe pasar las claves de valor de los elementos que desea seleccionar/deseleccionar:

    Seleccionar/deseleccionar algunos elementos:

    // Select/deselect items by their IDs as valueKey is set to 'id'
combo.select(['BG01', 'BG02', 'BG03', 'BG04']);
combo.deselect(['BG01', 'BG02', 'BG03', 'BG04']);

    Seleccionar/deseleccionar todos los elementos:

    // Select/deselect all items
combo.select();
combo.deselect();

    Si se omite la propiedad valueKey, deberá enumerar los elementos que desea seleccionar/deseleccionar como referencias de objetos:

    // Select/deselect values by object references when no valueKey is provided
combo.select([cities[1], cities[5]]);
combo.deselect([cities[1], cities[5]]);

    Validation

    El componente combinado Ignite UI for Web Components admite la mayoría de las propiedades IgcInputComponent, como required, disabled, autofocus, invalid, etc. El componente también expone dos métodos vinculados a su validación:

    • reportValidity: comprueba la validez y devuelve verdadero si el componente satisface las restricciones de validación.
    • checkValidity: un contenedor alrededor de reportValidity para cumplir con la API de entrada nativa.

    Keyboard Navigation

    Cuando el componente combinado está enfocado y la lista de opciones no está visible:

    • Abra la lista de opciones usando las teclas Abajo/Alt + Abajo.

    Cuando el componente combinado está enfocado y la lista de opciones está visible:

    • Usar la tecla Abajo activará el siguiente elemento de la lista.
    • Usar la tecla Arriba activará el elemento anterior de la lista. Si el primer elemento ya está activo, centrará la entrada.
    • El uso de las teclas Inicio o Fin activará el primero o el último elemento de la lista.
    • Usando la tecla Espacio se seleccionará el elemento activo.
    • Usar la tecla Enter seleccionará el elemento activo y cerrará la lista de opciones.
    • Usar las teclas Esc o Tab/Shift + Tab cerrará la lista de opciones.

    Styling Web Components ComboBox

    Puede cambiar la apariencia del componente IgcComboComponent Ignite UI for Web Components y sus elementos utilizando las partes CSS expuestas que se enumeran a continuación:

    CSS Parts

    Nombre de la pieza Descripción
    label La etiqueta de texto encapsulado.
    input El campo de entrada principal.
    native-input La entrada nativa del campo de entrada principal.
    prefix El contenedor de prefijo.
    suffix El contenedor del sufijo.
    toggle-icon El contenedor del icono de alternancia.
    clear-icon El contenedor de iconos claros.
    case-icon Un contenedor de ícono de caso que presenta contenido dentro del sufijo de la entrada del filtro.
    helper-text El contenedor de texto auxiliar.
    search-input El campo de entrada de búsqueda.
    list-wrapper La lista de opciones de contenedor.
    list El cuadro de lista de opciones.
    item Representa cada elemento de la lista de opciones.
    group-header Representa cada encabezado en la lista de opciones.
    active Se agrega a la lista de piezas del artículo cuando el artículo está activo.
    selected Se adjunta a la lista de piezas del artículo cuando se selecciona el artículo.
    checkbox Representa cada casilla de verificación de cada elemento de la lista.
    checkbox-indicator Representa el indicador de casilla de verificación de cada elemento de la lista.
    checked Se adjunta a la lista de piezas de la casilla de verificación cuando la casilla de verificación está marcada.
    header El contenedor que contiene el contenido del encabezado.
    footer El contenedor que contiene el contenido del pie de página.
    empty El contenedor que contiene el contenido vacío.

    API Reference

    Additional Resources