Visão geral do componente Angular ComboBox

O componente Angular ComboBox representa uma lista suspensa que fornece funcionalidades editáveis, permitindo que os usuários escolham várias opções de uma lista predefinida. O componente Ignite UI for Angular ComboBox também fornece recursos de filtragem, agrupamento e adição de valores personalizados a uma lista suspensa. Ele pode ser usado como uma alternativa à tag HTML select e tem vários recursos prontos para uso, como vinculação de dados (local e remoto), filtragem, agrupamento, modelos personalizados para itens, cabeçalho e rodapé, valores personalizados e muito mais.

Angular ComboBox Example

Neste exemplo Angular ComboBox, você pode ver como os usuários podem filtrar itens e executar a seleção com os dados fornecidos. Além disso, o ComboBox expõe recursos de navegação por teclado e estilo personalizado.

Angular ComboBox Features

O controle combobox expõe os seguintes recursos:

Ligação de dados - dados locais e dados remotos
Valor de ligação
Filtragem
Agrupamento
Valores personalizados
Modelos
Integração com formulários orientados a modelos e formulários reativos

Getting Started with Ignite UI for Angular ComboBox

Para começar a usar o componente Ignite UI for Angular ComboBox, primeiro você precisa instalar Ignite UI for Angular. Em um aplicativo Angular existente, digite o seguinte comando:

ng add igniteui-angular

Para obter uma introdução completa ao Ignite UI for Angular, leia o tópico de introdução.

O próximo passo é importar issoIgxComboModule no seu arquivo app.module.ts.

import { IgxComboModule } from 'igniteui-angular/combo';
// import { IgxComboModule } from '@infragistics/igniteui-angular'; for licensed package

@NgModule({
    imports: [
        ...
        IgxComboModule,
        ...
    ]
})
export class AppModule {}

Alternativamente,16.0.0 você pode importarIgxComboComponent como uma dependência independente ou usar oIGX_COMBO_DIRECTIVES token para importar o componente e todos os seus componentes e diretivas de suporte.

// home.component.ts

import { IGX_COMBO_DIRECTIVES } from 'igniteui-angular/combo';
// import { IGX_COMBO_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package

@Component({
    selector: 'app-home',
    template: '<igx-combo></igx-combo>',
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [IGX_COMBO_DIRECTIVES]
    /* or imports: [IgxComboComponent] */
})
export class HomeComponent {}

Agora que você importou o módulo ou diretivas Ignite UI for Angular Combo, pode começar a usar oigx-combo componente.

Using the Angular ComboBox Component

Após a configuração inicial, você pode vincular o igx-combo aos dados.

@Component({
    selector: 'app-combo-demo',
    template: '<igx-combo [data]="cities"></igx-combo>',
    styleUrls: ['combo-demo.component.scss'],
    standalone: true,
    imports: [IGX_COMBO_DIRECTIVES]
})
export class ComboDemo implements OnInit {
    public cities: { name: string, id: string }[] = [];

    public ngOnInit() {
        this.cities = [{ name: 'London', id: 'UK01' }, { name: 'Sofia', id: 'BG01'}, ...];
    }
}

Nossa combobox agora está vinculada ao array de cidades, mas ainda não dissemos ao componente qual propriedade usar para o texto dos itens e qual usar para o valor. Vamos fazer isso agora.

Data value and display properties

Como a combobox está vinculada a um array de dados complexos (ou seja, objetos), precisamos especificar uma propriedade que o controle usará para lidar com os itens selecionados. O controle expõe duas@Input propriedades -valueKey e displayKey:

valueKey-Opcional, recomendado para arrays de objetos- Especifica qual propriedade das entradas de dados será armazenada para a seleção da combobox. SevalueKey for omitido, o valor da caixa combobox usará referências às entradas de dados (ou seja, a seleção será um array de entradas de ).igxCombo.data
displayKey-Exigido para arrays de objetos- Especifica qual propriedade será usada para o texto dos itens. Se nenhum valor for especificado,displayKey a caixa combinada usará o especificadovalueKey (se houver).

No nosso caso, queremos que a combobox exiba oname de cada cidade e o valor da combobox armazene oid de cada cidade. Portanto, estamos fornecendo essas propriedades para os comboboxesdisplayKey evalueKey, respectivamente:

<igx-combo [data]="cities" displayKey="name" valueKey="id"></igx-combo>

Note

Quando a fonte de dados é um array de primitivas (por exemplostring[],),number[] não especifique umvalueKey edisplayKey. Valores primitivos serão usados tanto para valor quanto para texto.

Ligação bidirecional

O componente combobox suporta totalmente a vinculação de dados bidirecional,[(ngModel)] bem como o uso em formas baseadas em templates e reativas. A seleção de comboboxes pode ser acessada tanto por meio de binding bidirecional quanto pela API de seleção. Podemos passar um array de itens do mesmo tipo que os selecionados pela combobox (com base emvalueKey) e, sempre que um muda, o outro é atualizado de acordo.

No exemplo a seguir, as cidades de Sofia e Londres serão inicialmente selecionadas. Quaisquer mudanças adicionais na seleção da combobox refletirão oselectedCities array.

<igx-combo [data]="cities" [(ngModel)]="selectedCities" displayKey="name" valueKey="id"></igx-combo>

export class MyCombo {
    public cities: { name: string, id: string }[] = [
                   { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...];
    public selectedCities: string[] = ['BG01', 'UK01'];
}

A ligação bidirecional também pode ser realizada sem especificaçãovalueKey. Por exemplo, sevalueKey for omitido, o modelo ligado ficará assim:

export class MyCombo {
    public cities: { name: string, id: string } [] = [
                   { name: 'Sofia', id: 'BG01' }, { name: 'London', id: 'UK01' }, ...];
    public selectedCities: { name: string, id: string } [] = [this.cities[0], this.cities[1]];
}

Selection API

O componente combobox expõe uma API que permite obter e manipular o estado de seleção atual do controle.

Uma maneira de obter a seleção do combobox é por meio da propriedade selection. Ela retorna um array de valores que correspondem aos itens selecionados, dependendo do valueKey especificado (se houver).

No nosso exemplo,selection retornará um array das cidadesid selecionadas:

export class MyCombo {
    ...
    public selection: string[] = this.combo.selection;
}

Usando a API de seleção, você também pode alterar os itens selecionados da caixa de combinação sem interação do usuário com o controle - por meio de um clique de botão, como resposta a uma alteração do Observable, etc. Por exemplo, podemos implementar um botão que seleciona um conjunto de cidades, usando o método select():

<igx-combo [data]="cities" displayKey="name" valueKey="id"></igx-combo>
<button igxButton (click)="selectFavorites()">Select Favorites</button>

Ao clicar no botão, as cidades Londres e Sófia serão adicionadas à seleção do combobox:

export class MyExampleCombo {
    @ViewChild(IgxComboComponent, { read: IgxComboComponent, static: true })
    public combo: IgxComboComponent;
    ...
    selectFavorites(): void {
        this.combo.select(['UK01', 'BG01']);
    }
}

O combobox também dispara um evento toda vez que sua seleção muda -selectionChanging(). Os argumentos de evento emitidos, IComboSelectionChangingEventArgs, contêm informações sobre a seleção anterior à mudança, a seleção atual e os itens que foram adicionados ou removidos. O evento também pode ser cancelado, impedindo a atualização da seleção com o novo array de itens.

A vinculação ao evento pode ser feita através da propriedade correta@Output naigx-combo tag:

<igx-combo [data]="cities" displayKey="name" valueKey="id"
           (selectionChanging)="handleCityChange($event)">
</igx-combo>

No exemplo a seguir, quando uma cidade é adicionada ou removida da seleção, um manipulador que atualiza a visualização estatística é acionado:

export class MyExampleCombo {
    ...
    handleCityChange(event: IComboSelectionChangeEventArgs): void {
        for (const item of event.added) {
            this.addToVisualization(item);
        }
        for (const item of event.removed) {
            this.removeFromVisualization(item);
        }
    }
}

Single Selection

Por padrão, o controle de combo oferece múltiplas seleções. O trecho abaixo demonstra como alcançar uma única seleção no componente anexando um manipulador aoselectionChanging evento:

<igx-combo [data]="lData" (selectionChanging)="singleSelection($event)"></igx-combo>

public singleSelection(event: IComboSelectionChangeEventArgs) {
    if (event.added.length) {
        event.newValue = event.added;
    }
}

Nota: É recomendável usar o igxSimpleCombo em vez de modificar o igxCombo como mostrado acima.

Quando a caixa de combinação é fechada e focada:

ArrowDownouAlt +ArrowDown, vai abrir o menu suspenso da combobox e mover o foco para a entrada de busca.

Quando a caixa de combinação é aberta e a entrada de pesquisa é focada:

ArrowUpouAlt +ArrowUp vai fechar o menu suspenso da combobox e mover o foco para a combbox fechada.
ArrowDownVai mover o foco da entrada da busca para o primeiro item da lista. Se a lista estiver vazia e os valores personalizados estiverem ativados, ela será movida para o botão Adicionar novo item.

Note

Qualquer outro pressionamento de tecla será tratado pela entrada.

Quando a caixa de combinação é aberta e o item da lista é focalizado:

ArrowDownVou passar para o próximo item da lista. Se o item ativo for o último da lista e os valores personalizados estiverem ativados, o foco será movido para o botão Adicionar item.
ArrowUpVou passar para o item da lista anterior. Se o item ativo for o primeiro da lista, o foco será movido de volta para a entrada de busca.
EndVou passar para o último item da lista.
HomeVou passar para o primeiro item da lista.
SpaceVai selecionar/desmarcar o item da lista ativa.
EnterConfirmará os itens já selecionados e fechará a lista.
EscVou fechar a lista.

Quando a caixa de combinação é aberta, os valores personalizados são habilitados e o botão Adicionar item é destacado:

EnterAdicionará um novo item comvalueKey edisplayKey igual ao texto na entrada de busca e selecionará o novo item.
ArrowUpO foco será movido de volta para o último item da lista ou, se a lista estiver vazia, será movido para a entrada de busca.

Estilização

Combo Theme Property Map

Quando você modifica uma propriedade primária, todas as propriedades dependentes relacionadas são atualizadas automaticamente:

Propriedade primária	Propriedade dependente	Descrição
$empty-lista de contexto	$empty-lista-marca-marca-colorido	A cor provisória do texto combinado.
$toggle-botão de fundo	$toggle-botão em primeiro plano	O botão de combo alterna a cor do primeiro plano.
	$toggle-botão-fundo-foco	O botão de alternância do combo ativa a cor do fundo quando está focado.
	$toggle-botão-fundo-foco-borda	O botão de alternância do botão alterna a cor do fundo quando focado (variante na borda).
	$toggle-botão cheio de primeiro plano	O botão de combo alterna a cor do primeiro plano quando preenchido.
	$toggle-botão-fundo-desativado	O botão combo alterna a cor de fundo quando desativado.
	$toggle-botão em primeiro plano-desativado	O botão de alternar o combo ativa a cor do primeiro plano quando desativado.
$toggle-botão-fundo-foco	$toggle-botão de foco em primeiro plano	O botão de combo alterna a cor do primeiro plano quando está focado.
$clear-botão-fundo-foco	$clear-botão de foco em primeiro plano	O botão de combo limpar cor de primeiro plano quando focado.

Usando issoIgnite UI for Angular Theming, podemos alterar bastante a aparência da combobox. Primeiro, para usarmos as funções expostas pelo motor de temas, precisamos importar oindex arquivo no nosso arquivo de estilo:

@use "igniteui-angular/theming" as *;

// IMPORTANT: Prior to Ignite UI for Angular version 13 use:
// @import '~igniteui-angular/lib/core/styles/themes/index';

Seguindo a abordagem mais simples, criamos um novo tema que estende ocombo-theme. Ao definir o$toggle-button-background, o tema determina automaticamente as cores de estado adequadas e os primeiros planos de contraste para o botão. Você também pode especificar parâmetros adicionais, como$search-separator-border-color:

$custom-combo-theme: combo-theme(
  $search-separator-border-color: #1d3743,
  $toggle-button-background: #57a5cd,
);

EleIgxComboComponent usa oIgxDropDownComponent interno como um recipiente de itens. Também inclui osIgxInputGroup e osIgxCheckbox componentes. Criar novos temas que estendam os temas desses componentes e colocá-los sob as respectivas classes permitirá que você altere os estilos das comboboxs:

$custom-drop-down-theme: drop-down-theme(
  $background-color: #57a5cd,
);

$custom-checkbox-theme: checkbox-theme(
  $border-radius: 10px,
  $fill-color: #1d3743,
  $empty-color: #1d3743,
);

A última etapa é incluir o tema do componente.

:host ::ng-deep {
  @include css-vars($custom-combo-theme);
  @include css-vars($custom-drop-down-theme);
  @include css-vars($custom-checkbox-theme);
}

Note

OIgxCombo componente usa oIgxOverlay serviço para armazenar e exibir o contêiner da lista de itens combobox. Para definir corretamente seus estilos, talvez seja necessário usar umOverlaySetting.outlet. Para mais detalhes, consulte oIgxOverlay Styling Guide. Também é necessário usar::ng-deep quando estivermos estilizando os componentes.

Note

O padrãotype doIgxCombo ébox diferente doIgxSelect onde ele estáline.

Demo

Styling with Tailwind

Você pode usarcombo nossas classes utilitárias personalizadas de Tailwind. Certifique-se de configurar o Tailwind primeiro.

Junto com a importação de vento de cauda em sua folha de estilo global, você pode aplicar os utilitários de tema desejados da seguinte maneira:

@import "tailwindcss";
...
@use 'igniteui-theming/tailwind/utilities/material.css';

O arquivo utilitário inclui tantolight as variantes quantodark as do tema.

Uselight-* as aulas para o tema da luz.
Usedark-* classes para o tema sombrio.
Adicione o nome do componente após o prefixo, por exemplo,light-combo,dark-combo.

Uma vez aplicadas, essas classes possibilitam cálculos dinâmicos de temas. A partir daí, você pode sobrescrever as variáveis CSS geradas usandoarbitrary properties. Após os dois-pos, forneça qualquer formato de cor CSS válido (HEX, variável CSS, RGB, etc.).

Você pode encontrar a lista completa de propriedades no tema combinado. A sintaxe é a seguinte:

<igx-combo
class="!light-combo
![--toggle-button-background:#99BAA6]
![--clear-button-foreground:#99BAA6]"
...></igx-combo>

Note

O ponto de exclamação(!) é necessário para garantir que a classe utilitária tenha prioridade. O Tailwind aplica estilos em camadas e, sem marcar esses estilos como importantes, eles serão substituídos pelo tema padrão do componente.

No final, sua combinação deve ficar assim:

Known Issues

A entrada combobox que exibe os itens selecionados não é editável. No entanto, devido a especificações do navegador no FireFox, o cursor é visível.
Quando a caixa combobox está vinculada a um array de dados primitivos que contémundefined (ou seja[ undefined, ...]undefined), não é exibido no menu suspenso. Quando ele está vinculado a um array de dados complexos (ou seja, objetos) e o valor usado paravalueKey éundefined, o item será exibido no menu suspenso, mas não pode ser selecionado.
Quando a caixa de combinação estiver vinculada a um serviço remoto e houver uma seleção predefinida, sua entrada permanecerá em branco até que os dados solicitados sejam carregados.

Note

A combobox usaigxForOf diretiva internamente, portanto todasigxForOf as limitações são válidas para a combobox. Para mais detalhes, vejaigxForOf Known Issues a seção.

API Summary

Componentes angulares adicionais e/ou diretivas com APIs relativas que foram usadas:

Theming Dependencies

Additional Resources

Nossa comunidade é ativa e sempre acolhedora para novas ideias.

Visão geral do componente Angular ComboBox

Angular ComboBox Example

Angular ComboBox Features

Getting Started with Ignite UI for Angular ComboBox

Using the Angular ComboBox Component

Data value and display properties

Note

Ligação bidirecional

Selection API

Single Selection

Keyboard Navigation

Note

Estilização

Combo Theme Property Map

Note

Note

Demo

Styling with Tailwind

Note

Known Issues

Note

API Summary

Theming Dependencies

Additional Resources

Temas