Visão geral do componente Angular Drop Down

O Ignite UI for Angular Drop Down é um componente que exibe uma lista alternável de valores predefinidos e permite que os usuários selecionem facilmente um único item de opção com um clique. Ele pode ser configurado rapidamente para atuar como um menu suspenso ou você pode simplesmente usá-lo para fornecer informações visuais mais úteis agrupando dados. Com o agrupamento, você pode usar dados planos e hierárquicos. O componente Drop Down permite vinculação declarativa, o que torna possível incorporar conteúdo e links adicionais. Isso também deixa espaço para mais personalização da IU e estilo da aparência da lista suspensa Angular. Além disso, ele é repleto de recursos importantes, como navegação suspensa por teclado e virtualização.

Angular Drop Down Example

Este exemplo de drop down Angular demonstra as funcionalidades básicas de uma lista drop down. Clique nele para expandir as opções predefinidas, selecione um item e feche o drop down.

Getting Started with Ignite UI for Angular Drop Down

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

// app.module.ts

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

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

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

// home.component.ts

import { NgFor } from '@angular/common';
import { IGX_DROP_DOWN_DIRECTIVES, IgxToggleActionDirective, IgxButtonDirective } from 'igniteui-angular';
// import { IGX_DROP_DOWN_DIRECTIVES, IgxToggleActionDirective, IgxButtonDirective } from '@infragistics/igniteui-angular'; for licensed package

@Component({
  selector: 'app-home',
  template: `
    <button
      igxButton="contained"
      [igxToggleAction]="dropdown"
      [igxDropDownItemNavigation]="dropdown"
    >
      Options
    </button>
    <igx-drop-down #dropdown>
      <igx-drop-down-item *ngFor="let item of items">
        {{ item.field }}
      </igx-drop-down-item>
    </igx-drop-down>
  `,
  styleUrls: ['home.component.scss'],
  standalone: true,
  imports: [ IGX_DROP_DOWN_DIRECTIVES, IgxToggleActionDirective, IgxButtonDirective, NgFor ],
  /* or imports: [IgxDropDownComponent, IgxDropDownItemComponent, IgxToggleActionDirective, IgxButtonDirective, NgFor] */
})
export class HomeComponent {}

Agora que você importou o módulo Ignite UI for Angular Drop Down ou as diretivas, você pode começar a usar o componente igx-drop-down.

Using the Angular Drop Down

Add Drop Down

Vamos criar um drop-down simples que fornece vários itens de opção para escolher. Para conseguir isso, usaremos o IgxDropDownComponent, bem como o IgxToggleAction para abrir/fechar o drop-down.

<!-- dropdown.component.html -->
<button igxButton="contained" [igxToggleAction]="dropdown" [igxDropDownItemNavigation]="dropdown">
  Options
</button>
<igx-drop-down #dropdown>
  <igx-drop-down-item *ngFor="let item of items">
    {{ item.field }}
  </igx-drop-down-item>
</igx-drop-down>

// dropdown.component.ts
@Component({...})
export class MyDropDownComponent {
    public items: Array<{ field: string }> = [
        { field: 'Option 1' },
        { field: 'Option 2' },
        { field: 'Option 3' }
    ];
}

More Angular Drop Down Examples

A demonstração padrão mostra o uso de uma Drop Down List alternável no Angular que permite que os usuários finais expandam todos os itens predefinidos e optem por um deles. Confira o exemplo a seguir e veja a Drop Down List Angular em ação.

Predefined selected item

Digamos que queremos ter um item selecionado predefinido. Uma maneira de fazer isso é manipulando o evento de abertura do componente drop-down.

<!-- dropdown.component.html -->
<button igxButton="contained" [igxToggleAction]="dropdown" [igxDropDownItemNavigation]="dropdown">
  Options
</button>
<igx-drop-down #dropdown (opening)="dropdown.setSelectedItem(0)">
  <igx-drop-down-item *ngFor="let item of items">
    {{ item.field }}
  </igx-drop-down-item>
</igx-drop-down>

// dropdown.component.ts
export class MyDropDownComponent {
  public items: Array<{ field: string }> = [
    { field: 'Option 1' },
    { field: 'Option 2' },
    { field: 'Option 3' },
  ];
}

Grouping items

Para fornecer informações visuais mais úteis, use a propriedade isHeader para agrupar itens semanticamente ou a propriedade disabled para exibir um item como não interativo. Você também pode definir a propriedade selected em um item específico para torná-lo o item selecionado. Os itens igx-drop-down têm suporte pronto para uso para as diretivas igxPrefix, igxSuffix e igx-divider que podem conter ou ser definidas em elementos HTML ou outros componentes da web.

<!-- dropdown.component.html -->
<button igxButton="contained" [igxToggleAction]="dropdown" [igxDropDownItemNavigation]="dropdown">
  Countries
</button>
<igx-drop-down #dropdown [width]="'240px'">
  <div class="drop-down__scroll-container">
    <igx-drop-down-item *ngFor="let item of items" [disabled]="item.disabled" [isHeader]="item.header" [selected]="item.selected">
      <igx-icon igxPrefix>place</igx-icon>
      {{ item.field }}
      <span igxSuffix>{{ item.code }}</span>
      <igx-divider></igx-divider>
    </igx-drop-down-item>
  </div>
</igx-drop-down>

// dropdown.component.ts
export class MyDropDownComponent {
  public items: any[] = [
    { field: 'European Union', code: 'EU', header: true },
    { field: 'Germany', code: 'DE' },
    { field: 'Bulgaria', code: 'BG', selected: true },
    { field: 'France', code: 'FR', disabled: true },
    { field: 'North America', code: 'NA', header: true },
    { field: 'Canada', code: 'CA' },
    { field: 'United States', code: 'US' },
    { field: 'Mexico', code: 'MX' },
  ];
}

Se o exemplo estiver configurado corretamente, uma lista de países deverá ser exibida como um grupo sob o cabeçalho União Europeia, França como um item não interativo e Bulgária como um item selecionado:

Grouping hierarchical data

Os itens igx-drop-down também podem ser agrupados usando o contêiner igx-drop-down-item-group, facilitando para os usuários diferenciar categorias separadas. O igx-drop-down-item-group aceita elementos igx-drop-down-item como seu conteúdo e os renderiza de forma agrupada.

// dropdown.component.ts
export class MyCustomDropDownComponent {
    ...
    public foods: {
        name: string,
        entries: { name: string, refNo: string }[]
    }[] = [
    {
        name: 'Vegetables',
        entries: [{
            name: 'Cucumber',
            refNo: '00000'
        }, {
            name: 'Lettuce',
            refNo: '00001'
        },
        ...]
    }, {
        name: 'Fruits',
        entries: [{
            name: 'Banana',
            refNo: '10000'
        }, {
            name: 'Tomato',
            refNo: '10001'
        },
        ...]
    }, {
        name: 'Meats',
        entries: [{
            name: 'Chicken',
            refNo: '20000'
        }, {
            name: 'Beef',
            refNo: '20001'
        },
        ...]
    }];
}

<igx-drop-down>
  <igx-drop-down-item-group *ngFor="let foodGroup of foods" [label]="foodGroup.name">
    <igx-drop-down-item *ngFor="let food of foodGroup.entries" [value]="food.refNo">
      {{ food.name }}
    </igx-drop-down-item>
  </igx-drop-down-item-group>
</igx-drop-down>

O grupo também tem a funcionalidade adicional de desabilitar itens dentro de seu corpo. Por exemplo, digamos que não queremos que o grupo de alimentos Meats seja selecionável em nosso menu suspenso. Em vez de desabilitar todas as entradas em Meats separadamente, podemos desabilitar o grupo, bem como todos os itens filhos dentro dele:

<igx-drop-down>
  <igx-drop-down-item-group *ngFor="let foodGroup of foods" [label]="foodGroup.name" [disabled]="foodGroup.name === 'Meats'">
    <igx-drop-down-item *ngFor="let food of foodGroup.entries" [value]="food.refNo">
      {{ food.name }}
    </igx-drop-down-item>
  </igx-drop-down-item-group>
</igx-drop-down>

Você pode ver os resultados no exemplo abaixo:

Você pode configurar o menu suspenso para se comportar como um menu. Para fazer isso, defina o membro cancel da interface ISelectionEventArgs como true no manipulador de eventos selectionChanging. Dessa forma, o item selecionado não é preservado ao abrir o menu e as seleções anteriores são invalidadas. Ainda assim, você pode obter o item clicado por meio do valor do membro newSelection no evento.

<!-- dropdown.component.html -->
<div>
  <igx-navbar title="Contacts">
    <button
      [igxToggleAction]="menu"
      [igxToggleOutlet]="outlet"
      [overlaySettings]="overlaySettings"
      [igxDropDownItemNavigation]="menu"
      igxIconButton="flat"
    >
      <igx-icon fontSet="material">more_vert</igx-icon>
    </button>
    <igx-drop-down #menu (selectionChanging)="selectionHandler($event)">
      <igx-drop-down-item *ngFor="let item of items" [value]="item.text">
        <div>{{ item.text }}</div>
      </igx-drop-down-item>
    </igx-drop-down>
  </igx-navbar>

  <div>
    <ng-container *ngIf="text">
      <label igxLabel>{{ text }}</label>
    </ng-container>
  </div>

  <div igxOverlayOutlet #outlet="overlay-outlet"></div>
</div>

// dropdown.component.ts
export class MyMenuComponent {
  public items: Array<{ text: string }> = [
    { text: "Add New Contact" },
    { text: "Edit Contact" },
    { text: "Refresh" },
    { text: "Help" },
  ];
  public text: string;
  public overlaySettings = {
    positionStrategy: new ConnectedPositioningStrategy({
      horizontalDirection: HorizontalAlignment.Left,
      horizontalStartPoint: HorizontalAlignment.Right,
      verticalStartPoint: VerticalAlignment.Bottom,
    }),
    scrollStrategy: new NoOpScrollStrategy(),
  };

  public selectionHandler(eventArgs: ISelectionEventArgs) {
    this.text = eventArgs.newSelection.value;
    eventArgs.cancel = true;
  }
}

O exemplo a seguir demonstra como implementar um menu suspenso de vários níveis que permite ao usuário navegar de forma rápida e fácil por uma hierarquia de conteúdo passando o mouse sobre uma série de menus aninhados.

Para a implementação do menu suspenso multinível, usaremos o IgxDropDownComponent, bem como uma diretiva e serviço personalizados descritos abaixo.

Para configurar o IgxDropDownItem para abrir um menu suspenso adicional, adicione a diretiva multiLevel que manipulará as overlay settings do menu suspenso aninhado e gerenciará seu estado aberto/fechado por meio de sua propriedade innerDropdown.

<igx-drop-down #dropdown1>
  <igx-drop-down-item [value]="'Web'" multiLevel [innerDropdown]="web">
    Web <igx-icon igxSuffix>chevron_right</igx-icon>
  </igx-drop-down-item>
  ...
</igx-drop-down>

<igx-drop-down #web>
  <igx-drop-down-item [value]="'App Builder'"> App Builder </igx-drop-down-item>
  ...
</igx-drop-down>

Para configurar o menu suspenso multinível para se comportar como um menu, você precisa manipular o evento selectionChanging de todos os menus suspensos na hierarquia e cancelar o comportamento padrão. Então, para manipular a seleção corretamente, você pode usar o método handleSelection do MultiLevelService e, para evitar fechar o menu suspenso ao clicar em um item de menu, use os métodos handleClosing do MultiLevelService.

@ViewChildren(IgxDropDownComponent, { read: IgxDropDownComponent })
private _dropdowns: QueryList<IgxDropDownComponent>;

@ViewChild('dropdown1', { read: IgxDropDownComponent })
private _multiLevelDropdown: IgxDropDownComponent;

constructor(private _multiLevelService: MultiLevelService) { }

public ngAfterViewInit(): void {
    this._dropdowns.forEach((dropdown) => {
        dropdown.selectionChanging.subscribe((args) => {
            args.cancel = true;
            const value = args.newSelection.value;
            const categories = this._multiLevelService.categories;

            if (categories.includes(value)) {
                this.selection = '';
                return;
            }

            if (this._multiLevelService.isMultiLevel(dropdown)) {
                this._multiLevelService.handleSelection();
            } else {
                dropdown.close();
            }

            this.selection = value;
        });
    });

    this._multiLevelDropdown.closing.subscribe((args) => {
        this._multiLevelService.handleClosing(args);
    });
}

O resultado das configurações acima pode ser visto no exemplo abaixo.

Note

Para exibir o componente Dropdown aberto inicialmente, é recomendado definir o método open como um retorno de chamada do método requestAnimationFrame. Isso garantirá que a árvore DOM seja repintada e que todos os elementos sejam posicionados corretamente.

Use a diretiva igxDropDownItemNavigation para habilitar a navegação pelo teclado para o componente igxDropDown. Para permitir que a diretiva manipule todos os eventos disparados, ela deve ser aplicada ao elemento ativo (focado) ou a um contêiner pai. Por padrão, um menu suspenso ou seus itens não recebem foco, então a diretiva pode ser colocada em um button ou input que controlará o menu suspenso. O valor da diretiva de navegação deve ter como alvo um componente que seja uma instância ou um descendente da classe IgxDropDownBaseDirective.

O exemplo a seguir demonstra uma entrada que abre e fecha a instância igxDropDown ao clicar. Aplicar a diretiva igxDropDownItemNavigation na própria entrada habilitará a navegação pelo teclado ao usar as teclas de seta para cima e para baixo. Isso depende do comportamento padrão do menu suspenso com a propriedade allowItemsFocus definida como false para permitir que a entrada mantenha o foco.

<!-- input-dropdown.component.html -->
<igx-input-group #inputGroup [igxToggleAction]="dropDown">
  <input
    type="text"
    igxInput
    [igxDropDownItemNavigation]="dropDown"
    readonly="true"
    placeholder="choose an option"
    [value]="dropDown.selectedItem?.value"
    (keydown.ArrowDown)="openDropDown()"
  />

  <igx-suffix igxIconButton="flat" igxRipple>
    <igx-icon>arrow_drop{{ dropDown.collapsed ? '_down' : '_up' }}</igx-icon>
  </igx-suffix>
</igx-input-group>

<span>Selected: {{ dropDown.selectedItem?.value }}</span>
<igx-drop-down #dropDown [width]="'160px'">
  <igx-drop-down-item *ngFor="let item of items" [value]="item.field">
    {{ item.field }}
  </igx-drop-down-item>
</igx-drop-down>

// input-dropdown.component.ts
export class InputDropDownComponent {
  @ViewChild(IgxDropDownComponent) public igxDropDown: IgxDropDownComponent;
  @ViewChild('inputGroup', { read: IgxInputGroupComponent })
  public inputGroup: IgxInputGroupComponent;

  public items: Array<{ field: string }> = [
    { field: 'Option 1' },
    { field: 'Option 2' },
    { field: 'Option 3' },
  ];

  public openDropDown() {
    if (this.igxDropDown.collapsed) {
      this.igxDropDown.open({
        modal: false,
        positionStrategy: new ConnectedPositioningStrategy({
          target: this.inputGroup.element.nativeElement,
        }),
      });
    }
  }
}

A aplicação da diretiva garantirá que as seguintes ações sejam executadas como resultado da navegação pelo teclado:

Nome	Descrição
`Enter`	Selecione o item no menu suspenso e feche o menu suspenso.
`Space`	Selecione o item no menu suspenso e feche o menu suspenso.
`Esc`	Fecha o menu suspenso.
`Arrow Down`	Navegue até o próximo item no componente de destino.
`Arrow Up`	Navegue até o item anterior no componente de destino.
`End`	Navegue até o último item no componente de destino.
`Home`	Navegue até o primeiro item no componente de destino.

Quando a propriedade allowItemsFocus está habilitada, os itens suspensos ganham índice de tabulação e são focados quando ativos. Os itens suspensos focados são aqueles que disparam eventos, durante a navegação pelo teclado, o que significa que a diretiva de navegação deve ser aplicada aos itens suspensos individuais.

<igx-input-group [igxToggleAction]="dropDown">
  <input igxInput type="text" />
</igx-input-group>
<igx-drop-down #dropDown [allowItemsFocus]="true">
  <igx-drop-down-item *ngFor="let p of provinceData" [igxDropDownItemNavigation]="dropDown">
    {{ p }}
  </igx-drop-down-item>
</igx-drop-down>

Estilização

Usando o Ignite UI for Angular Theming, podemos alterar muito a aparência do menu suspenso. 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 drop-down-theme e aceita alguns dos parâmetros do tema padrão.

$custom-drop-down-theme: drop-down-theme(
  $background-color: #fdfdfd,
  $header-text-color: #345779,
  $item-text-color: #2dabe8,
  $selected-item-background: #345779,
  $selected-item-text-color: #fdfdfd,
  $selected-hover-item-background: #345779,
  $selected-hover-item-text-color: #fdfdfd,
  $selected-focus-item-background: #345779,
  $selected-focus-item-text-color: #fdfdfd,
  $hover-item-background: rgba(0, 0, 0, 0.12),
  $hover-item-text-color: #345779,
);

O último passo é passar o tema suspenso personalizado para um seletor de classe ou elemento:

.drop-down__scroll-container {
  @include css-vars($custom-drop-down-theme);
}

Visão geral do componente Angular Drop Down

Angular Drop Down Example

Getting Started with Ignite UI for Angular Drop Down

Using the Angular Drop Down

Add Drop Down

More Angular Drop Down Examples

Predefined selected item

Grouping items

Grouping hierarchical data

Drop Down as menu

Multi-Level Drop Down menu

Note

Navigation directive

Estilização

Demo

API Summary

Theming Dependencies

Additional Resources

Temas