Visão geral do componente Angular Single Select ComboBox

O componente Angular Single Select ComboBox é uma modificação do componente ComboBox que permite seleção única. Nós o chamamos de "combo simples". Devido à alta demanda pelo modo de seleção única para o componente ComboBox original, criamos um componente de extensão que oferece uma entrada de pesquisa editável que permite aos usuários escolher uma opção de uma lista predefinida de itens e inserir valores personalizados.

Angular Simple ComboBox Example

Neste exemplo Angular Simple ComboBox, você pode ver como os usuários podem selecionar o tipo de linha de tendência do gráfico. Além disso, o Simple ComboBox expõe recursos de navegação por teclado e estilo personalizado.

Angular Simple ComboBox Features

O controle combobox simples expõe os seguintes recursos: - Vinculação de dados - dados locais e remotos - Vinculação de valores - Filtragem - Agrupamento - Valores personalizados - Modelos - Integração com formulários orientados a modelos e formulários reativos

Getting Started with Ignite UI for Angular Simple ComboBox

Para começar a usar o componente Ignite UI for Angular Simple 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 IgxSimpleComboModule no seu arquivo app.module.ts.

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

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

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

// home.component.ts

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

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

Agora que você importou o módulo Ignite UI for Angular Simple ComboBox ou as diretivas, você pode começar a usar o componente igx-simple-combo.

Using the Angular Simple ComboBox

Assim como a combobox normal, você pode vincular o igx-simple-combo aos dados.

export class MySimpleComboComponent implements OnInit {
    public cities: City[];

    public ngOnInit() {
        this.cities = getCitiesByPopulation(10000000);
    }
}

<igx-simple-combo [data]="cities"></igx-simple-combo>

Nossa caixa de combinação simples agora está vinculada ao conjunto de cidades.

Data value and display properties

Como o combobox simples é 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 simples. Se valueKey for omitido, o valor do combobox simples usará referências às entradas de dados (ou seja, a seleção será um array de entradas de igxSimpleCombo.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 simples usará o valueKey especificado (se houver).

No nosso caso, queremos que o combobox simples exiba o name de cada cidade e seu valor para armazenar o id de cada cidade. Portanto, estamos vinculando essas propriedades como valores ao displayKey e valueKey do combobox simples, respectivamente:

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

Note

Quando a fonte de dados for composta de um tipo simples (por exemplo, string[], number[]), não especifique valueKey e displayKey.

Ligação bidirecional

O componente combobox simples 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 combobox simples pode ser acessada por meio da vinculação bidirecional ou pela API de seleção. Podemos passar um item do mesmo tipo que os da seleção da combobox simples (com base em valueKey) e sempre que um muda, o outro é atualizado de acordo.

No exemplo a seguir, a primeira cidade nos dados fornecidos será inicialmente selecionada. Quaisquer outras alterações na seleção do combobox simples refletirão em selectedCities.

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

export class MySimpleComboComponent implements OnInit {
    public cities: City[];
    public selectedCity: number;

    public ngOnInit(): void {
        this.cities = getCitiesByPopulation(10000000);
        this.selectedCity = this.cities[0].id;
    }
}

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 MySimpleComboComponent {
    public cities: City[] = [
                   { name: 'Sofia', id: '1' }, { name: 'London', id: '2' }, ...];
    public selectedCity: City = this.cities[0];
}

Selection API

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

Uma maneira de obter sua seleção é por meio da propriedade selection. Ela retorna um valor que corresponde ao item selecionado, dependendo do valueKey especificado (se houver).

Em nosso exemplo, selection retornará o id da cidade selecionada:

export class MySimpleComboComponent {
    ...
    public selection: string = this.simpleCombo.selection;
}

Usando a API de seleção, você também pode alterar o item selecionado da combobox simples sem interação do usuário com o controle - por meio de um clique de botão, como uma resposta a uma alteração do Observable, etc. Por exemplo, podemos implementar um botão que seleciona uma cidade, usando o método select:

<igx-simple-combo [data]="cities" [displayKey]="'name'" [valueKey]="'id'"></igx-simple-combo>
<button igxButton (click)="selectFavorite()">Select Favorite</button>

Quando o botão for clicado, London será adicionada à seleção da caixa de combinação simples:

export class MySimpleComboComponent {
    @ViewChild(IgxSimpleComboComponent, { read: IgxSimpleComboComponent, static: true })
    public simpleCombo: IgxSimpleComboComponent;
    ...
    selectFavorites(): void {
        this.simpleCombo.select('2');
    }
}

O combobox simples também dispara um evento toda vez que sua seleção muda -selectionChanging. Os argumentos de evento emitidos, ISimpleComboSelectionChangingEventArgs, contêm informações sobre a seleção anterior à mudança, a seleção atual e o item exibido. O evento também pode ser cancelado, impedindo que a seleção ocorra.

A vinculação ao evento pode ser feita por meio da propriedade @Output apropriada na tag igx-simple-combo:

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

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

ArrowDown ou Alt + ArrowDown abrirá o menu suspenso da caixa de combinação simples.

Note

Qualquer outro pressionamento de tecla será tratado pela entrada.

Quando a caixa de combinação simples é aberta e um item na 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 enquanto também seleciona todo o texto na entrada.
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 selecionará/desmarcará o item ativo da lista e fechará a lista.
Esc fechará a lista.

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

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

Cascading Scenario

O exemplo a seguir demonstra um cenário onde o igx-simple-combo é usado:

Confira nosso exemplo de grade Angular com combinações em cascata.

Template Configuration

A API do combobox simples é usada para obter o item selecionado de um componente e carregar a fonte de dados para o próximo, além de limpar a seleção e a fonte de dados quando necessário.

<igx-simple-combo #country
    [data]="countriesData"
    (selectionChanging)="countryChanging($event)"
    placeholder="Choose Country..."
    [(ngModel)]="selectedCountry"
    [displayKey]="'name'">
</igx-simple-combo>
<igx-simple-combo #region
    [data]="regionData"
    (selectionChanging)="regionChanging($event)"
    placeholder="Choose Region..."
    [(ngModel)]="selectedRegion"
    [displayKey]="'name'"
    [disabled]="regionData.length === 0">
</igx-simple-combo>
<igx-simple-combo #city
    [data]="citiesData"
    placeholder="Choose City..."
    [(ngModel)]="selectedCity"
    [displayKey]="'name'"
    [disabled]="citiesData.length === 0">
</igx-simple-combo>

Component Definition

export class SimpleComboCascadingComponent implements OnInit {
    public selectedCountry: Country;
    public selectedRegion: Region;
    public selectedCity: City;
    public countriesData: Country[];
    public regionData: Region[] = [];
    public citiesData: City[] = [];
    public ngOnInit(): void {
        this.countriesData = getCountries(['United States', 'Japan', 'United Kingdom']);
    }

    public countryChanging(e: ISimpleComboSelectionChangingEventArgs) {
        this.selectedCountry = e.newSelection as Country;
        this.regionData = getCitiesByCountry([this.selectedCountry?.name])
            .map(c => ({name: c.region, country: c.country}))
            .filter((v, i, a) => a.findIndex(r => r.name === v.name) === i);
        this.selectedRegion = null;
        this.selectedCity = null;
        this.citiesData = [];
    }

    public regionChanging(e: ISimpleComboSelectionChangingEventArgs) {
        this.selectedRegion = e.newSelection as Region;
        this.citiesData = getCitiesByCountry([this.selectedCountry?.name])
            .filter(c => c.region === this.selectedRegion?.name);
        this.selectedCity = null;
    }
}

Angular Simple ComboBox Remote Binding

O componente Ignite UI for Angular Simple ComboBox expõe uma API que permite vincular uma combobox a um serviço remoto e recuperar dados sob demanda.

Demo

O exemplo abaixo demonstra a vinculação remota usando a propriedade dataPreLoad para carregar um novo bloco de dados remotos e seguindo as etapas descritas em Vinculação remota do ComboBox:

Estilização

Usando o Ignite UI for Angular Theming, podemos alterar muito a aparência do combobox simples. 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 $empty-list-background:

$custom-simple-combo-theme: combo-theme(
  $empty-list-background: #1a5214
);

O IgxSimpleComboComponent usa o IgxDropDownComponent internamente como um contêiner de itens. Ele também inclui o componente IgxInputGroup. Criar novos temas, que estendem os temas desses componentes, e defini-los sob as respectivas classes permitirá que você altere os estilos simples de 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,
);

A última etapa é incluir o tema do componente.

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

Note

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

Note

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

Demo

Known Issues

O combobox simples não tem entrada para dimensionar sua altura. No futuro, o componente IgxInputGroup irá expor uma opção que permite dimensionamento personalizado, e então o IgxSimpleCombo usará a mesma funcionalidade para estilo adequado e melhor consistência.
Quando o combobox simples é 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 o combobox simples é vinculado via ngModel e marcado como required, os valores null, undefined e'' não podem ser selecionados.
Quando a caixa de combinação simples 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 simples usa a diretiva igxForOf internamente, portanto todas as limitações igxForOf são válidas para o combobox simples. Para mais detalhes, veja a seção Problemas conhecidos do igxForOf.

Visão geral do componente Angular Single Select ComboBox

Angular Simple ComboBox Example

Angular Simple ComboBox Features

Getting Started with Ignite UI for Angular Simple ComboBox

Using the Angular Simple ComboBox

Data value and display properties

Note

Ligação bidirecional

Selection API

Keyboard Navigation

Note

Cascading Scenario

Template Configuration

Component Definition

Angular Simple ComboBox Remote Binding

Demo

Estilização

Note

Note

Demo

Known Issues

Note

API Summary

Theming Dependencies

Additional Resources

Temas