Visão geral da diretiva Angular Autocomplete
Angular Autocomplete é uma diretiva de caixa de pesquisa que permite que os usuários encontrem, filtrem e selecionem facilmente um item de uma lista de sugestões enquanto digitam. Rico em recursos, ele suporta vinculação de dados contínua, filtragem, agrupamento, opções de personalização de IU e outras funcionalidades integradas para que os desenvolvedores possam criar uma experiência de pesquisa de preenchimento automático intuitiva.
A diretiva igxAutocomplete fornece uma maneira de aprimorar uma entrada de texto mostrando um igxDropDown com opções sugeridas, fornecidas pelo desenvolvedor. As sugestões serão exibidas quando você começar a digitar na entrada de texto ou usar as teclas Arrow Up / Arrow Down.
Angular Autocomplete Example
O exemplo de preenchimento automático Angular abaixo gera uma lista suspensa de sugestões conforme os usuários começam a digitar o nome de uma cidade na caixa de texto de entrada.
Getting Started with Ignite UI for Angular Autocomplete
Para começar a usar o Ignite UI for Angular para Angular Components e a diretiva Autocomplete em particular, 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 IgxAutocompleteModule e o IgxDropDownModule em nosso app.module. Se igxAutocomplete for aplicado em um igxInput, o igxInputGroupModule também será necessário:
// app.module.ts
...
import {
IgxAutocompleteModule,
IgxDropDownModule,
IgxInputGroupModule
} from 'igniteui-angular';
// import { IgxAutocompleteModule, IgxDropDownModule, IgxInputGroupModule } from '@infragistics/igniteui-angular'; for licensed package
@NgModule({
...
imports: [
...,
IgxAutocompleteModule,
IgxDropDownModule,
IgxInputGroupModule,
....
],
...
})
export class AppModule {}
Como alternativa, a partir da 16.0.0 você pode importar a IgxAutocompleteDirective como uma diretiva autônoma.
// home.component.ts
...
import { IgxAutocompleteDirective, IGX_INPUT_GROUP_DIRECTIVES, IGX_DROP_DOWN_DIRECTIVES } from 'igniteui-angular';
// import { IgxAutocompleteDirective, IGX_INPUT_GROUP_DIRECTIVES, IGX_DROP_DOWN_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package
@Component({
selector: 'app-home',
template: `
<igx-input-group>
<input igxInput name="towns" type="text" [igxAutocomplete]="townsPanel" />
<label igxLabel for="towns">Towns</label>
</igx-input-group>
<igx-drop-down #townsPanel>
<igx-drop-down-item *ngFor="let town of towns">
{{town}}
</igx-drop-down-item>
</igx-drop-down>
`,
styleUrls: ['home.component.scss'],
standalone: true,
imports: [IgxAutocompleteDirective, IGX_INPUT_GROUP_DIRECTIVES, IGX_DROP_DOWN_DIRECTIVES]
})
export class HomeComponent {}
Agora que você importou o módulo ou a diretiva Ignite UI for Angular Action Strip, você pode começar com uma configuração básica do componente igxAutocomplete.
Using the Angular Autocomplete
Para aplicar a funcionalidade de preenchimento automático a uma entrada, adicione a diretiva igxAutocomplete, referenciando o menu suspenso:
<igx-input-group>
<input igxInput name="towns" type="text" [igxAutocomplete]="townsPanel" />
<label igxLabel for="towns">Towns</label>
</igx-input-group>
<igx-drop-down #townsPanel>
<igx-drop-down-item *ngFor="let town of towns">
{{town}}
</igx-drop-down-item>
</igx-drop-down>
Adicione a lista que será mostrada no dropdown. Se quiser que a lista seja filtrada enquanto digita, use a interface PipeTransform.
import { Component, Pipe, PipeTransform } from '@angular/core';
@Component({
selector: 'app-autocomplete-sample',
styleUrls: ['autocomplete.sample.css'],
templateUrl: `autocomplete.sample.html`
})
export class AutocompleteSampleComponent {
constructor() {
this.towns = [ 'New York', 'Washington, D.C.', 'London', 'Berlin', 'Sofia', 'Rome', 'Kiev',
'Copenhagen', 'Paris', 'Barcelona', 'Vienna', 'Athens', 'Dublin', 'Yerevan',
'Oslo', 'Helsinki', 'Stockholm', 'Prague', 'Istanbul', 'El Paso', 'Florence', 'Moscow' ];
}
}
@Pipe({ name: 'startsWith' })
export class AutocompletePipeStartsWith implements PipeTransform {
public transform(collection: any[], term = '') {
return collection.filter((item) => item.toString().toLowerCase().startsWith(term.toString().toLowerCase()));
}
}
Note
O igxAutocomplete usa o igxDropDown como um provedor para as opções disponíveis, o que significa que todos os recursos do componente suspenso podem ser usados no preenchimento automático.
Disable Angular Autocomplete
Você pode desabilitar o preenchimento automático Angular usando a entrada IgxAutocompleteDisabled:
<igx-input-group>
<input igxInput name="towns" type="text"
[igxAutocomplete]='townsPanel'
[igxAutocompleteDisabled]="disabled"/>
<label igxLabel for="towns">Towns</label>
</igx-input-group>
Autocomplete Settings
O posicionamento do menu suspenso igx-autocomplete, a estratégia de rolagem e a saída podem ser configurados usando IgxAutocompleteSettings.
No exemplo de Autocomplete Angular a seguir, posicionaremos o dropdown acima da entrada e desabilitaremos as animações de abertura e fechamento. Estamos usando ConnectedPositioningStrategy para isso:
<igx-input-group class="autocomplete">
<label igxLabel for="cinema">Cinema</label>
<input igxInput name="cinema" type="text"
[igxAutocomplete]="townsPanel"
[igxAutocompleteSettings]="settings"/>
</igx-input-group>
<igx-drop-down #townsPanel maxHeight="300px">
<igx-drop-down-item-group *ngFor="let town of towns" [label]="town.name">
<igx-drop-down-item *ngFor="let cinema of town.cinemas" [value]="cinema">
{{cinema}}
</igx-drop-down-item>
</igx-drop-down-item-group>
</igx-drop-down>
export class AutocompleteComponent {
public settings = {
positionStrategy: new ConnectedPositioningStrategy({
closeAnimation: null,
openAnimation: null,
verticalDirection: VerticalAlignment.Top,
verticalStartPoint: VerticalAlignment.Top
})
};
public towns = [
{
name: 'New York',
cinemas: [
'Regal Cinemas',
'Village East Cinema',
'Roxy Cinema',
'The Paris Theatre'
]},
{
name: 'Los Angeles',
cinemas: [
'Arc Light',
'Pacific Cinerama Dome',
'New Beverly Cinema',
'Downtown Independent'
]},
{
name: 'Seattle',
cinemas: [
'Central Cinema',
'Grand Illusion Cinema',
'Ark Lodge Cinemas',
'Skyway Outdoor Cinema'
]}
];
}
Note
A estratégia de posicionamento padrão é AutoPositionStrategy e o menu suspenso é aberto de acordo com o espaço disponível.
Se tudo correr bem, você deverá ver isto no seu navegador:
Keyboard Navigation
- ⬆ / ⬇ ou digitar a entrada abrirá o menu suspenso, se estiver fechado.
- ⬇- moverá para o próximo item suspenso.
- ⬆- moverá para o item suspenso anterior.
- ENTER confirmará o item já selecionado e fechará o menu suspenso.
- ESC fechará o menu suspenso.
Note
Quando o Angular autocomplete abre, então o primeiro item da lista é selecionado automaticamente. O mesmo é válido quando a lista é filtrada.
Você também pode ver como nosso WYSIWYG App Builder ™ simplifica toda a história do design ao código em 80% usando componentes Angular reais.
Compatibility support
A aplicação da diretiva igxAutocomplete decorará o elemento com os seguintes atributos ARIA:
- role="combobox" - função do elemento, onde a diretiva é aplicada.
- aria-autocomplete="list" - indica que as sugestões de conclusão de entrada são fornecidas na forma de lista
- Atributo aria-haspopup="listbox" para indicar que
igxAutocompletepode exibir um contêiner para sugerir valores. - aria-expanded="true"/"false" - valor dependendo do estado recolhido do menu suspenso.
- aria-owns="dropDownID" - id do menu suspenso usado para exibir sugestões.
- aria-activedescendant="listItemId" - o valor é definido como o id do elemento da lista ativa atual.
O componente drop-down, usado como provedor de sugestões, exporá os seguintes atributos ARIA:
- role="listbox" - aplicado no contêiner do componente
igx-drop-down - role="group" - aplicado no contêiner do componente
igx-drop-down-item-group - role="option" - aplicado no contêiner do componente
igx-drop-down-item - aria-disabled="true"/"false" aplicado nos contêineres de componentes
igx-drop-down-itemeigx-drop-down-item-groupquando eles estão desabilitados.
Estilização
Cada componente tem seu próprio tema.
Para estilizar o igxAutocomplete, você precisa estilizar os componentes que o contêm. No nosso caso, esses são o input-group-theme e o drop-down-theme.
Dê uma olhada nas seções de estilo igxInputGroup e igxDropdown para entender melhor como estilizar esses dois componentes.
API Reference
Theming Dependencies
Additional Resources
Nossa comunidade é ativa e sempre acolhedora para novas ideias.
GitHub