Visão geral do Blazor ComboBox

Blazor 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 de teclado Blazor ComboBox, modelos para personalizar como os itens, cabeçalho e rodapé são exibidos.

O componente Ignite UI for Blazor ComboBox 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 complexa e muito mais.

Blazor ComboBox Example

Getting Started with Blazor ComboBox

Para começar a usar o componente IgbCombo, primeiro precisamos registrar seu módulo da seguinte maneira:

// in Program.cs file

builder.Services.AddIgniteUIBlazor(typeof(IgbComboModule));

Você também precisará vincular um arquivo CSS adicional para aplicar o estilo ao componente IgbCombo. O seguinte precisa ser colocado no arquivo wwwroot/index.html em um projeto Blazor Web Assembly ou no arquivo Pages/_Host.cshtml em um projeto Blazor Server:

<link href="_content/IgniteUI.Blazor/themes/light/bootstrap.css" rel="stylesheet" />

[!WARNING] The IgbCombo 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.

<IgbCombo Id="basic-combo" DisplayKey="name" ValueKey="id" Data="Data" />

@code {
    private class City {
        public string Id { get; set; }
        public string Name { get; set; }
        public string Country { get; set; }
    }

    private List<City> Data = new List<City> {
        new City {
            Id = "UK01",
            Name = "London",
            Country = "United Kingdom",
        },
        new City {
            Id = "BG01",
            Name = "Sofia",
            Country = "Bulgaria",
        },
        new City {
            Id = "US01",
            Name = "New York",
            Country = "United States",
        },
    };
}

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 o 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:

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 uma 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:

<IgbCombo
    @ref="Combo"
    Label="Cities"
    Placeholder="Pick a city"
    Data="Data"
    ValueKey="Id"
    DisplayKey="Name">
</IgbCombo>

@code {
    private List<City> Data;
    private IgbCombo Combo;
    private object[] Cities;

    protected override void OnInitialized() {
        this.Data = SampleData.Cities;
        this.Cities = new object[] { "UK01", "UK02", "UK03", "UK04", "UK05" };
    }

    public void SelectCities() {
        this.Combo.Select(Cities);
    }

    public void DeselectCities() {
        this.Combo.Deselect(Cities);
    }
}

Selecionar/desmarcar todos os itens:

@code {
    public void SelectAll() {
        this.Combo.Select(new object[] {});
    }

    public void DeselectAll() {
        this.Combo.Deselect(new object[] {});
    }
}

Se a propriedade ValueKey for omitida, você terá que listar os itens que deseja selecionar/desmarcar como referências de objetos:

Validation

O componente Ignite UI for Blazor Combo oferece suporte à maioria das propriedades IgbInput, 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 IgbCombo 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);
}