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

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

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

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

// home.component.ts

import { IGX_SIMPLE_COMBO_DIRECTIVES } from 'igniteui-angular/simple-combo';
// 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 ou diretivas Ignite UI for Angular Simple ComboBox, pode começar a usar oigx-simple-combo componente.

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

No nosso caso, queremos que a caixa combinada simples exiba oname de cada cidade e seu valor para armazenar oid de cada cidade. Portanto, estamos vinculando essas propriedades como valores aos comboboxesdisplayKey simples evalueKey, respectivamente:

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

Observação

Quando a fonte de dados é composta por um tipo simples (por exemplostring[]),number[]​ ​não especifique umvalueKey edisplayKey.

Ligação bidirecional

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

No exemplo a seguir, a primeira cidade dos dados fornecidos será inicialmente selecionada. Quaisquer mudanças adicionais na seleção da caixa combobox simples refletirão oselectedCities.

<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 ligação bidirecional também pode ser realizada sem especificaçãovalueKey. Por exemplo, sevalueKey for omitido, o modelo ligado 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).

No nosso exemplo,selection retornará a cidadeid 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 é clicado,London será adicionado à seleção da caixa de combo:

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 através da propriedade correta@Output naigx-simple-combo tag:

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

Navegação pelo teclado

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

• ArrowDownouAlt +ArrowDown vai abrir o menu suspenso da caixa de comboboxes simples.

Observação

Qualquer outro pressionamento de tecla será tratado pela entrada.

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

• EndVou passar para o último item da lista.

• HomeVou passar para o primeiro item da lista.

• SpaceVai selecionar/desmarcar o item da lista ativa.

• EnterVai selecionar/desmarcar o item da lista ativa e fechar a lista.

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

• EnterAdicionará um novo item comvalueKey edisplayKey igual ao texto na entrada de busca e selecionará o novo item.

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

Configuração do modelo

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>

Definição de componente

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 issoIgnite UI for Angular Theming, podemos alterar bastante a aparência simples da caixa combinada. 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 e aceita o$empty-list-background parâmetro:

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

EleIgxSimpleComboComponent usa oIgxDropDownComponent interno como um recipiente de itens. Também inclui oIgxInputGroup componente. Criar novos temas que estendam os temas desses componentes e colocá-los sob as respectivas classes permitirá que você mude 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);
}

Observação

OIgxSimpleCombo componente usa oIgxOverlay serviço para armazenar e exibir o simples contêiner de 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.

Observação

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

Demo

Problemas conhecidos

• 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 a caixa combobox simples 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 combobox simples é vinculada viangModel e é marcada comorequired,null,undefined e'' os valores 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.

Observação

A combobox simples usaigxForOf diretiva internamente, portanto todasigxForOf as limitações são válidas para a combobox simples. Para mais detalhes, veja a seção igxForOf Problemas Conhecidos.

Resumo da API

• IgxSimpleComboComponent
• Estilos de IgxComboComponent

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

• Componente IgxDropDown
• Componente do grupo de entrada Igx

Theming Dependencies

• Tema IgxDropDown
• Tema IgxIcon
• Tema IgxOverlay

Recursos adicionais

• 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

Nossa comunidade é ativa e sempre acolhedora para novas ideias.

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