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 T="object" 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:

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

<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 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.

Keyboard Navigation

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

API Reference

• IgbCombo
• Styling & Themes

Additional Resources

• Ignite UI for Blazor Fóruns
• Ignite UI for Blazor GitHub