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

Em seguida, você precisará importar o React IgrCombo 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- *Obrigatório, se valueKey for omitido, deve ser definido como "objeto", caso contrário, precisa corresponder ao tipo de propriedade de valueKey.

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 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 por meio dos select métodos e deselect. Você pode passar uma matriz de itens para ambos os métodos. Se os métodos forem chamados sem argumentos, todos os itens serão selecionados/desmarcados dependendo de qual método é chamado. Se você especificou um valueKey para o seu componente de combinação, então você deve passar as chaves de valor dos itens que você gostaria de selecionar/desmarcar:

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"]);

Selecionar/desmarcar todos os itens:

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

Validation

O componente Ignite UI for React Combo suporta a IgrInput maioria das propriedades, como required, disabled, autofocus, invalid, etc. O componente também expõe dois métodos associados à sua validação:

reportValidity- verifica a validade e retorna true se o componente atender às 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

Você pode alterar a aparência do IgrCombo 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);
}