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 {}

Now that you have the Ignite UI for Angular Combo module or directives imported, you can start using the igx-combo component.

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

Since the combobox is bound to an array of complex data (i.e. objects), we need to specify a property that the control will use to handle the selected items. The control exposes two @Input properties - valueKey and displayKey:

• valueKey - Optional, recommended for object arrays - Specifies which property of the data entries will be stored for the combobox's selection. If valueKey is omitted, the combobox value will use references to the data entries (i.e. the selection will be an array of entries from igxCombo.data).
• displayKey - Required for object arrays - Specifies which property will be used for the items' text. If no value is specified for displayKey, the combobox will use the specified valueKey (if any).

In our case, we want the combobox to display the name of each city and the combobox value to store the id of each city. Therefore, we are providing these properties to the combobox's displayKey and valueKey, respectively:

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

Note

When the data source is an array of primitives (e.g. string[], number[]), do not specify a valueKey and displayKey. Primitive values will be used for both value and text.

Ligação bidirecional

The combobox component fully supports two-way data-binding with [(ngModel)] as well as usage in template driven and reactive forms. The combobox selection can be accessed either through two-way binding or through the selection API. We can pass an array of items of the same type as the ones in the combobox's selection (based on valueKey) and any time one changes, the other is updated accordingly.

In the following example, the cities Sofia and London will initially be selected. Any further changes in the combobox's selection will reflect on the selectedCities 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).

In our example, selection will return an array of the selected cities' ids:

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

By default, the combo control provides multiple selection. The snippet below demonstrates how to achieve single selection in the component by attaching a handler to the selectionChanging event:

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

Keyboard Navigation

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

• ArrowDown or Alt + ArrowDown will open the combobox's drop down and will move focus to the search input.

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

• ArrowUp or Alt + ArrowUp will close the combobox's drop down and will move focus to the closed combobox.

• ArrowDown will move focus from the search input to the first list item. If the list is empty and custom values are enabled will move it to the Add new item button.

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.

• ArrowUp will move to the previous list item. If the active item is the first one in the list, the focus will be moved back to the search input.

• EndVou passar para o último item da lista.

• HomeVou passar para o primeiro item da lista.

• SpaceVai selecionar/desmarcar o item da lista ativa.

• Enter will confirm the already selected items and will close the list.

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

• ArrowUp focus will be moved back to the last list item or if the list is empty, will be moved to the search input.

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.

Using the Ignite UI for Angular Theming, we can greatly alter the combobox appearance. First, in order for us to use the functions exposed by the theme engine, we need to import the index file in our style file:

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

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

Following the simplest approach, we create a new theme that extends the combo-theme. By setting the $toggle-button-background, the theme automatically determines suitable state colors and contrast foregrounds for the button. You can also specify additional parameters, such as $search-separator-border-color:

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

The IgxComboComponent uses the IgxDropDownComponent internally as an item container. It also includes the IgxInputGroup and the IgxCheckbox components. Creating new themes, that extend these components' themes, and scoping them under the respective classes will let you change the combobox styles:

$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

The IgxCombo component uses the IgxOverlay service to hold and display the combobox items list container. To properly scope your styles you might have to use an OverlaySetting.outlet. For more details check the IgxOverlay Styling Guide. Also is necessary to use ::ng-deep when we are styling the components.

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.
• When the combobox is bound to an array of primitive data which contains undefined (i.e. [ undefined, ...]), undefined is not displayed in the dropdown. When it is bound to an array of complex data (i.e. objects) and the value used for valueKey is undefined, the item will be displayed in the dropdown, but cannot be selected.
• 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

The combobox uses igxForOf directive internally hence all igxForOf limitations are valid for the combobox. For more details see igxForOf Known Issues section.

API Summary

• Componente IgxCombo
• Estilos de IgxComboComponent

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

• Componente IgxDropDown
• Componente do grupo de entrada Igx
• Componente IgxCheckbox

Theming Dependencies

• Tema IgxDropDown
• Tema IgxIcon
• Tema IgxCheckbox
• Tema IgxOverlay

Additional Resources

• Recursos do ComboBox
• Ligação remota do ComboBox
• Modelos de ComboBox
• Integração de formulários orientados a modelos
• Integração de Formulários Reativos
• ComboBox de seleção única

Nossa comunidade é ativa e sempre acolhedora para novas ideias.

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