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 oIgcComboComponent componente, 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 Comecando.

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:

T-required, sevalueKey for omitido, isso deve ser definido como "object", caso contrário isso precisa corresponder ao tipo de propriedade devalueKey.

valueKey-Opcional, necessário para objeto de dados complexo - Determina qual campo da fonte de dados será usado para fazer seleções. SevalueKey for omitida, a API de seleção usará referências a objetos para selecionar itens.
displayKey- Opcional, recomendado para objetos de dados complexos - Determina qual campo na fonte de dados é usado como valor de exibição. Se nenhum valor for especificado,displayKey a combinação usará o especificadovalueKey (se houver). No nosso caso, queremos que a combinação mostre oname de cada cidade e use oid campo para seleção de itens e como valor subjacente para cada item. Portanto, fornecemos essas propriedades para as combinaçõesvalueKey edisplayKey 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 umvalue getter e um setter além de um atributo, que também é chamado de valor. Você pode usar o atributo valor para definir os itens selecionados na inicialização dos componentes.

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

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 pelosselect métodos e (edeselect methods). Você pode passar uma variedade 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 avalueKey para seu componente de combo, então deve passar as chaves de valor dos itens que 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']);

Selecione/desmarque todos os itens

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

Se avalueKey propriedade for omitida, você terá que listar os itens que deseja selecionar/desmarcar como referências a 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 suporta a maioria dasIgcInputComponent propriedades, comorequired,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 ao redor do reportValidity para cumprir a API nativa de entrada.

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 HOME teclas ou END ativará o primeiro ou o último item da lista.
Usando a SPACE chave selecionará o item ativo.
Usando a ENTER chave, selecionará o item ativo e fechará a lista de opções.
Usar as ESC teclas ou TAB/SHIFT + TAB fechará a lista de opções.

Styling

Você pode alterar a aparência doIgcComboComponent componente e seus itens usando as partes CSS expostas listadas abaixo:

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.

Usando as partes CSS, temos controle total sobre o estilo Combo.

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