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

// app.module.ts

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

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

Alternativamente,16.0.0 você pode importarIgxDropDownComponent como uma dependência independente ou usar oIGX_DROP_DOWN_DIRECTIVES token 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 } from 'igniteui-angular/drop-down';
import { IgxToggleActionDirective } from 'igniteui-angular/directives';
import { IgxButtonDirective } from 'igniteui-angular/directives';
// 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 ou diretivas Ignite UI for Angular Drop Down, pode começar a usar oigx-drop-down componente.

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 uma informação visual mais útil, use a propriedade isHeader para agrupar itens semanticamente ou a propriedade desabilitada para exibir um item como não interativo. Você também pode definir a propriedade selecionada em um item específico para torná-lo o item selecionado. Osigx-drop-down itens possuem suporte pronto para uso paraigxPrefix,igxSuffix, eigx-divider diretivas que podem conter ou ser definidas em elementos HTML ou outros componentes 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

Osigx-drop-down itens também podem ser agrupados usando o recipienteigx-drop-down-item-group, facilitando para os usuários diferenciarem categorias separadas. Aceitaigx-drop-down-item-group​igx-drop-down-item elementos como seu conteúdo e os apresenta 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 desativar itens dentro do corpo. Por exemplo, digamos que não queremos que oMeats grupo alimentar seja selecionável no menu suspenso. Em vez de desabilitar todas as entradas separadamenteMeats, podemos desabilitar o grupo, assim como todos os itens filhos dentro:

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

Drop Down as menu

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

Multi-Level Drop Down menu

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 oIgxDropDownComponent menu e uma diretiva e serviço personalizados descritos abaixo.

Para configurar aIgxDropDownItem abertura de um menu suspenso adicional, adicione amultiLevel diretriz que trate dooverlay settings menu aninhado e gerencie seu estado aberto/fechado por meio de suainnerDropdown propriedade.

<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 funcionar como um menu, você precisa lidar com o evento selectionChanging de todos os menus suspensos na hierarquia e cancelar o comportamento padrão. Então, para gerenciar a seleção corretamente, você pode usar o método theMultiLevelService​handleSelection 's e, para evitar fechar o menu suspenso ao clicar em um item do menu, usar os métodos theMultiLevelService​handleClosing 's.

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

Navigation directive

Use a diretiva igxDropDownItemNavigation para habilitar a navegação por teclado doigxDropDown componente. Para permitir que a diretiva gerencie todos os eventos acionados, 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 diretriz pode ser colocada em umbutton ouinput que controlará o menu suspenso. O valor da diretiva de navegação deve direcionar um componente que seja uma instância ou um descendente da classe IgxDropDownBaseDirective.

O exemplo a seguir demonstra uma entrada que abre e fecha aigxDropDown instância ao clique. Aplicar a diretiva igxDropDownItemNavigation na própria entrada permitirá a navegação por teclado ao usar as setas para cima e para baixo. Isso depende do comportamento padrão do menu suspenso com a propriedade allowItemsFocus configurada parafalse 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 aallowItemsFocus propriedade está ativada, os itens suspensos ganham índice de aba e são focados quando ativos. Os itens suspensos focados são os que acionam eventos durante a navegação por teclado, o que significa que a diretiva de navegação deve ser aplicada aos itens individuais do menu suspenso.

<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

Dropdown 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
$background cor	$item-text-color	A cor do texto do item suspenso.
	$hover-itens-contexto	O menu suspenso do item de fundo do curso.
	$focused-item-contexto	O menu suspenso focava na cor de fundo do item.
	$focused-item-texto-cor	O menu suspenso focava na cor do texto do item.
	$selected-Contexto de item	O menu suspenso selecionou a cor de fundo do item.
	$disabled-item-texto-cor	O menu suspenso desativou a cor do texto dos itens.
	$header-cor-texto	A cor do texto do cabeçalho suspenso.
$item-text-color	$item-cor-ícone-	A cor do ícone do item suspenso.
	$hover-item-texto-cor	O item suspenso paira na cor do texto.
	$hover-item-ícone-cor	O item suspenso paira na cor do ícone do cursor.
$selected-Contexto de item	$selected-item-text-color	O menu suspenso selecionou a cor do texto do item.
	$selected-item-ícone-cor	O menu suspenso selecionou a cor do ícone do item.
	$selected-hover-item-background	O menu suspenso selecionou o item passando o mouse sobre a cor de fundo.
	$selected-passar-surto-item-text-color	O menu suspenso selecionou o item para passar o mouse na cor do texto.
	$selected-passar o rato-ico-ícone-icônico-cor	O menu suspenso seleciona o item de cor do ícone de passageiro.
	$selected-foco-item-fundo	O menu suspenso seleciona o item foca na cor de fundo.
	$selected-foco-item-texto-cor	O menu suspenso selecionou a cor do texto do foco do item.
	$focused-item-cor-borda-	O item suspenso focava na cor da borda.

Usando a Ignite UI for Angular Theming, podemos alterar bastante a aparência do menu suspenso. 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 edrop-down-theme aceita alguns dos parâmetros padrão do tema. Quando você fornece uma certa cor de fundo, o tema calcula automaticamente as cores de estado e os primeiros planos contrastantes apropriados. Ao definir a$background propriedade, você obterá um menu suspenso totalmente estilizado.

$custom-drop-down-theme: drop-down-theme(
  $header-text-color: #345779,
  $item-text-color: #2dabe8,
  $hover-item-text-color: #345779,
  $selected-item-background: #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);
}

Demo

API Summary

• Componente IgxDropDown
• Estilos de componentes IgxDropDown
• Componente IgxDropDownItem.
• IgxOverlay
• Estilos IgxOverlay
• IgxDividerDirective
• Estilos de IgxDividerDirective

Theming Dependencies

• Tema IgxOverlay

Additional Resources

Nossa comunidade é ativa e sempre acolhedora para novas ideias.

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