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 o IgxComboModule no seu arquivo app.module.ts.

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

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

Como alternativa, a partir da 16.0.0, você pode importar o IgxComboComponent como uma dependência autônoma ou usar o token IGX_COMBO_DIRECTIVES para importar o componente e todos os seus componentes e diretivas de suporte.

// home.component.ts

import { IGX_COMBO_DIRECTIVES } from 'igniteui-angular';
// 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 Ignite UI for Angular Combo ou as diretivas, você pode começar a usar o componente igx-combo.

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 o combobox está vinculado a um array de dados complexos (ou seja, objetos), precisamos especificar uma propriedade que o controle usará para manipular os itens selecionados. O controle expõe duas propriedades @Input-valueKey e displayKey:

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

No nosso caso, queremos que o combobox exiba o name de cada cidade e o valor do combobox armazene o id de cada cidade. Portanto, estamos fornecendo essas propriedades para displayKey e valueKey do combobox, respectivamente:

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

Note

Quando a fonte de dados for uma matriz de primitivos (por exemplo, string[], number[]), não especifique valueKey e displayKey. Valores primitivos serão usados para value e text.

Ligação bidirecional

O componente combobox suporta totalmente a vinculação de dados bidirecional com [(ngModel)], bem como o uso em formulários reativos e orientados a modelos. A seleção do combobox pode ser acessada por meio da vinculação bidirecional ou pela API de seleção. Podemos passar uma matriz de itens do mesmo tipo que os da seleção do combobox (com base em valueKey) e sempre que um muda, o outro é atualizado de acordo.

No exemplo a seguir, as cidades Sofia e Londres serão selecionadas inicialmente. Quaisquer outras alterações na seleção do combobox refletirão no array selectedCities.

<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 vinculação bidirecional também pode ser alcançada sem um valueKey especificado. Por exemplo, se valueKey for omitido, o modelo vinculado 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).

Em nosso exemplo, selection retornará uma matriz dos id das cidades 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 por meio da propriedade @Output apropriada na tag igx-combo:

<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 combo fornece seleção múltipla. O snippet abaixo demonstra como obter seleção única no componente anexando um manipulador ao evento selectionChanging:

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

ArrowDown ou Alt + ArrowDown abrirá o menu suspenso da caixa de combinação e moverá o foco para a entrada de pesquisa.

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

ArrowUp ou Alt + ArrowUp fechará o menu suspenso da caixa de combinação e moverá o foco para a caixa de combinação fechada.
ArrowDown moverá o foco da entrada de pesquisa para o primeiro item da lista. Se a lista estiver vazia e os valores personalizados estiverem habilitados, moverá 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:

ArrowDown moverá para o próximo item da lista. Se o item ativo for o último da lista e os valores personalizados estiverem habilitados, o foco será movido para o botão Adicionar item.
ArrowUp moverá para o item anterior da lista. Se o item ativo for o primeiro da lista, o foco será movido de volta para a entrada de pesquisa.
End moverá para o último item da lista.
Home será movida para o primeiro item da lista.
Space selecionará/desselecionará o item ativo da lista.
Enter confirmará os itens já selecionados e fechará a lista.
Esc fechará a lista.

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

Enter adicionará um novo item com valueKey e displayKey iguais ao texto na entrada de pesquisa e selecionará o novo item.
O foco ArrowUp será movido de volta para o último item da lista ou, se a lista estiver vazia, será movido para a entrada de pesquisa.

Estilização

Usando o Ignite UI for Angular Theming, podemos alterar muito a aparência do combobox. Primeiro, para usarmos as funções expostas pelo mecanismo de tema, precisamos importar o arquivo index em 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 o combo-theme e aceita o parâmetro $search-separator-border-color:

$custom-combo-theme: combo-theme(
  $search-separator-border-color: #1a5214
);

O IgxComboComponent usa o IgxDropDownComponent internamente como um contêiner de itens. Ele também inclui os componentes IgxInputGroup e IgxCheckbox. Criar novos temas, que estendem os temas desses componentes, e defini-los sob as respectivas classes permitirá que você altere os estilos do combobox:

$custom-drop-down-theme: drop-down-theme(
  $background-color: #d9f5d6,
  $header-text-color: #1a5214,
  $item-text-color: #1a5214,

  $focused-item-background: #72da67,
  $focused-item-text-color: #1a5214,
  $hover-item-background: #a0e698,
  $hover-item-text-color: #1a5214,

  $selected-item-background: #a0e698,
  $selected-item-text-color: #1a5214,
  $selected-hover-item-background: #72da67,
  $selected-hover-item-text-color: #1a5214,
  $selected-focus-item-background: #72da67,
  $selected-focus-item-text-color: #1a5214,
);

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

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

O componente IgxCombo usa o serviço IgxOverlay para armazenar e exibir o contêiner de lista de itens do combobox. Para definir o escopo de seus estilos corretamente, você pode ter que usar um OverlaySetting.outlet. Para mais detalhes, consulte o IgxOverlay Styling Guide. Também é necessário usar::ng-deep quando estivermos estilizando os componentes.

Note

O type padrão do IgxCombo é box diferente do IgxSelect, onde é line.

Demo

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 o combobox é vinculado a uma matriz de dados primitivos que contém undefined (ou seja, [ undefined, ...]), undefined não é exibido no menu suspenso. Quando ele é vinculado a uma matriz de dados complexos (ou seja, objetos) e o valor usado para valueKey é undefined, o item será exibido no menu suspenso, mas não poderá 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

O combobox usa a diretiva igxForOf internamente, portanto todas as limitações igxForOf são válidas para o combobox. Para mais detalhes, veja a seção igxForOf Known Issues.

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

Note

Note

Demo

Known Issues

Note

API Summary

Theming Dependencies

Additional Resources

Temas