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 com oIgbCombo componente, primeiro precisamos registrar seu módulo da seguinte forma:

// in Program.cs file

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

Você também precisará vincular um arquivo CSS adicional para aplicar o estilo aoIgbCombo componente. O seguinte deve 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-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:

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

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

Selecione/desmarque todos os itens

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

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

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

Validation

O componente Ignite UI for Blazor Combo suporta a maioria dasIgbInput 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.

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