React ComboBox Overview

React 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 oferece suporte a opções para navegação React teclado ComboBox, modelos para personalizar como os itens, cabeçalho e rodapé são exibidos.

O componente ComboBox Ignite UI for React fornece uma lista de opções a partir 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 distinção entre maiúsculas e minúsculas, agrupamento, vinculação de dados complexos e muito mais.

React ComboBox Example

Getting Started with React ComboBox

Primeiro, você precisa instalar o pacote npm Ignite UI for React correspondente executando o seguinte comando:

npm install igniteui-react

Você então precisará importar o ReactIgrCombo e seu CSS necessário:

import { IgrCombo } from 'igniteui-react';
import 'igniteui-webcomponents/themes/light/bootstrap.css';

[!WARNING] The IgrCombo 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" },
];

<IgrCombo
    valueKey="id"
    displayKey="name"
    data={cities}
    value={["BG01"]}
></IgrCombo>

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 comboRef = useRef<IgrCombo>(null);

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

// Change the selected items to New York and London
comboRef.current.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'
comboRef.current.select(["UK01", "UK02", "UK03", "UK04", "UK05"]);
comboRef.current.deselect(["UK01", "UK02", "UK03", "UK04", "UK05"]);

Selecione/desmarque todos os itens

// Select/deselect all items
comboRef.current.select([]);
comboRef.current.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
comboRef.current.select([cities[1], cities[5]]);
comboRef.current.deselect([cities[1], cities[5]]);

Validation

O componente Ignite UI for React Combo suporta a maioria dasIgrInput 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 doIgrCombo 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);
}