Visão geral Web Components ComboBox

Web Components ComboBox é um editor leve que permite aos usuários selecionar, filtrar e agrupar facilmente diferentes opções predefinidas em uma lista fornecida. O componente também suporta opções para navegação de teclado Web Components ComboBox, modelos para personalizar como os itens, cabeçalho e rodapé são exibidos.

O componente ComboBox do Ignite UI for Web Components fornece uma lista de opções das quais os usuários podem fazer uma seleção. Ele exibe todas as opções em uma lista virtualizada de itens, o que significa que o ComboBox pode mostrar simultaneamente milhares de registros, onde uma ou mais opções podem ser selecionadas. Além disso, o componente apresenta filtragem com diferenciação entre maiúsculas e minúsculas, agrupamento, vinculação de dados complexos e muito mais.

Web Components ComboBox Example

Getting Started with Web Components ComboBox

Primeiro, você precisa instalar o Ignite UI for Web Components executando o seguinte comando:

npm install igniteui-webcomponents

Antes de usar o componente ComboBox, você precisa registrá-lo junto com seus componentes adicionais e o CSS necessário:

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

defineComponents(IgcComboComponent);

Para uma introdução completa ao Ignite UI for Web Components, leia o tópico Introdução.

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

Em seguida, vincularemos uma matriz de objetos à fonte de dados combinada usada para criar a lista de opções.

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

Quando o combo é vinculado a uma lista de dados complexos (ou seja, objetos), precisamos especificar uma propriedade que o controle usará para manipular a seleção de itens. O componente expõe as seguintes propriedades:

valueKey-Opcional, necessário para objeto de dados complexo- Determina qual campo da fonte de dados será usado para fazer seleções. Se valueKey for omitido, a API de seleção usará referências de objeto para selecionar itens.
displayKey-Opcional, recomendado para objetos de dados complexos- Determina qual campo na fonte de dados é usado como o valor de exibição. Se nenhum valor for especificado para displayKey, o combo usará o valueKey especificado (se houver). No nosso caso, queremos que o combo exiba o name de cada cidade e use o campo id para seleção de itens e como o valor subjacente para cada item. Portanto, fornecemos essas propriedades para valueKey e displayKey do 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

O componente ComboBox expõe um getter e setter value, além de um atributo, que também é chamado de value. Você pode usar o atributo value para definir os itens selecionados na inicialização do componente.

Se você quiser ler o valor, ou seja, a lista de itens selecionados atualmente, ou atualizar o valor, use o value getter e setter respectivamente. O value getter retornará uma lista de todos os itens selecionados, conforme representado pelo valueKey. Da mesma forma, se você quiser atualizar a lista de itens selecionados usando o value setter, você deve fornecer uma lista de itens por seu valueKey.

Exemplo:

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

O componente combo expõe APIs que permitem alterar os itens selecionados no momento.

Além de selecionar itens da lista de opções por interação do usuário, você pode selecionar itens programaticamente. Isso é feito por meio dos métodos select e deselect. Você pode passar um array de itens para ambos os métodos. Se os métodos forem chamados sem argumentos, todos os itens serão selecionados/desselecionados dependendo de qual método for chamado. Se você especificou um valueKey para seu componente combo, então você deve passar as chaves de valor dos itens que você gostaria de selecionar/desselecionar:

Selecione/desmarque alguns itens:

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

Selecionar/desmarcar todos os itens:

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

Se a propriedade valueKey for omitida, você terá que listar os itens que deseja selecionar/desmarcar como referências 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

O componente Ignite UI for Web Components Combo oferece suporte à maioria das propriedades IgcInputComponent, como required, disabled, autofocus, invalid, etc. O componente também expõe dois métodos vinculados à sua validação:

reportValidity- verifica a validade e retorna verdadeiro se o componente satisfaz as restrições de validação.
checkValidity- um wrapper em torno de reportValidity para estar em conformidade com a API de entrada nativa.

Quando o componente combo está em foco e a lista de opções não está visível:

Abra a lista de opções usando as teclas Baixo/Alt + Baixo.

Quando o componente combo está em foco e a lista de opções está visível:

Usar a tecla Para baixo ativará o próximo item na lista.
Usar a tecla Up ativará o item anterior na lista. Se o primeiro item já estiver ativo, ele focará a entrada.
Usar as teclas Home ou End ativará o primeiro ou o último item da lista.
Usar a tecla Espaço selecionará o item ativo.
Usar a tecla Enter selecionará o item ativo e fechará a lista de opções.
Usar as teclas Esc ou Tab/Shift + Tab fechará a lista de opções.

Styling

You can change the appearance of the IgcComboComponent component and its items, by using the exposed CSS parts listed below:

Nome da peça	Descrição
`label`	O rótulo de texto encapsulado.
`input`	O campo de entrada principal.
`native-input`	A entrada nativa do campo de entrada principal.
`prefix`	O wrapper de prefixo.
`suffix`	O wrapper de sufixo.
`toggle-icon`	O wrapper do ícone de alternância.
`clear-icon`	O wrapper de ícone transparente.
`case-icon`	Um wrapper de ícone de caso que renderiza conteúdo dentro do sufixo da entrada do filtro.
`helper-text`	O wrapper de texto auxiliar.
`search-input`	O campo de entrada de pesquisa.
`list-wrapper`	A lista de opções do wrapper.
`list`	A caixa de lista de opções.
`item`	Representa cada item na lista de opções.
`group-header`	Representa cada cabeçalho na lista de opções.
`active`	Acrescentado à lista de peças do item quando o item está ativo.
`selected`	Acrescentado à lista de peças do item quando o item é selecionado.
`checkbox`	Representa cada caixa de seleção de cada item da lista.
`checkbox-indicator`	Representa o indicador de caixa de seleção de cada item da lista.
`checked`	Acrescentado à lista de peças da caixa de seleção quando a caixa de seleção está marcada.
`header`	O contêiner que contém o conteúdo do cabeçalho.
`footer`	O contêiner que contém o conteúdo do rodapé.
`empty`	O recipiente que contém o conteúdo vazio.

Using the CSS parts we have full control over the Combo styling.

igc-combo::part(search-input) {
  background-color: var(--ig-gray-100);
  border-radius: 2px;
}

igc-combo::part(input) {
  background-color: var(--ig-gray-100);
}

igc-combo::part(prefix) {
  background-color: var(--ig-secondary-50);
  color: var(--ig-primary-500);
}

igc-combo::part(toggle-icon) {
  color: var(--ig-primary-500);
}