Visão geral do componente Angular List View
O componente Ignite UI for Angular List exibe linhas de itens e suporta um ou mais itens de cabeçalho, bem como pesquisa e filtragem de itens de lista. Cada item de lista é completamente modelável e suporta qualquer componente HTML ou Angular válido. O componente de lista também fornece funcionalidade de panorâmica integrada, modelos para estados vazios e de carregamento e suporta virtualização para listas grandes usando a diretiva IgxForOf.
Angular List Example
O exemplo a seguir representa uma lista preenchida com contatos com propriedades de nome e número de telefone. O componente IgxList usa igx-avatar e igx-icon para enriquecer a experiência do usuário e expor os recursos de configuração de imagem de avatar e ícone diferente para favoritar um contato. Além disso, a List View expõe recursos de classificação obtidos usando nosso pipe de filtragem.
Getting Started with Ignite UI for Angular List
Para começar a usar o componente Ignite UI for Angular List View, 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 IgxListModule no arquivo app.module.ts.
Note
Este componente pode utilizar o HammerModule opcionalmente. Ele pode ser importado no módulo raiz do aplicativo para que as interações por toque funcionem conforme o esperado.
// app.module.ts
import { HammerModule } from '@angular/platform-browser';
import { IgxListModule } from 'igniteui-angular';
// import { IgxListModule } from '@infragistics/igniteui-angular'; for licensed package
@NgModule({
...
imports: [..., IgxListModule, HammerModule],
...
})
export class AppModule {}
Como alternativa, a partir da 16.0.0, você pode importar o IgxListComponent como uma dependência autônoma ou usar o token IGX_LIST_DIRECTIVES para importar o componente e todos os seus componentes e diretivas de suporte.
// home.component.ts
import { HammerModule } from '@angular/platform-browser';
import { IGX_LIST_DIRECTIVES } from 'igniteui-angular';
// import { IGX_LIST_DIRECTIVES } from '@infragistics/igniteui-angular'; for licensed package
@Component({
selector: 'app-home',
template: `
<igx-list>
<igx-list-item isHeader="true">Header</igx-list-item>
<igx-list-item>Item 1</igx-list-item>
<igx-list-item>Item 2</igx-list-item>
<igx-list-item>Item 3</igx-list-item>
</igx-list>
`,
styleUrls: ['home.component.scss'],
standalone: true,
imports: [IGX_LIST_DIRECTIVES, HammerModule]
/* or imports: [IgxListComponent, IgxListItemComponent, HammerModule] */
})
export class HomeComponent {}
Agora que você importou o módulo Ignite UI for Angular List ou as diretivas, você pode começar a usar o componente igx-list.
Using the Angular List
Então, no template do nosso componente contacts podemos criar nossa lista, mas e se atualmente (ou em algum momento no futuro) não tivermos itens nela? Nesse caso, a lista Angular nos fornece um template padrão que é usado quando a lista está vazia. Podemos sempre fornecer nosso próprio template para a aparência da nossa lista vazia simplesmente usando a diretiva igxEmptyList. Nesse caso, o template padrão não será usado:
<!--contacts.component.html-->
<igx-list>
<ng-template igxEmptyList>
<p class="empty">No contacts! :(</p>
</ng-template>
</igx-list>
E nosso estilo para o modelo vazio:
/* contacts.component.css */
.empty {
color: rgba(0, 153, 255, 1);
font-size: 25px;
font-weight: 600;
text-shadow: 2px 1px 2px rgba(150, 150, 150, 1);
}
Se tudo correr bem, é assim que nossa lista vazia deve ficar:
Às vezes, pode haver um atraso no carregamento de seus dados. Nesse caso, você pode definir a propriedade isLoading da lista como true e um modelo padrão informará o usuário sobre o processo de carregamento de dados em andamento. Você também pode fornecer seu próprio modelo de carregamento usando a diretiva igxDataLoading:
<!--contacts.component.html-->
<igx-list>
<ng-template igxDataLoading>
<p class="loading">Patience, we are currently loading your data...</p>
</ng-template>
</igx-list>
/* contacts.component.css */
.loading {
color: rgba(255, 153, 0, 1);
font-size: 25px;
font-weight: 600;
text-shadow: 2px 1px 2px rgba(150, 150, 150, 1);
}
Add List Items
É legal ter um modelo para quando a lista estiver vazia, mas agora vamos adicionar alguns itens! Podemos adicionar o seguinte código para obter uma lista simples de itens:
<!--contacts.component.html-->
<igx-list>
<igx-list-item isHeader="true">Header</igx-list-item>
<igx-list-item>Item 1</igx-list-item>
<igx-list-item>Item 2</igx-list-item>
<igx-list-item>Item 3</igx-list-item>
</igx-list>
Se tudo correr bem, você deverá ver o seguinte no seu navegador:
Vamos melhorar um pouco o nosso jogo e aprimorar os itens da nossa lista. Digamos que queremos criar uma lista Angular de contatos com um nome e um número de telefone exibidos abaixo do nome. Em nosso arquivo typescript do componente, podemos definir uma lista de contatos:
// contacts.component.ts
...
public contacts = [{
name: "Terrance Orta",
phone: "770-504-2217"
}, {
name: "Richard Mahoney",
phone: "423-676-2869"
}, {
name: "Donna Price",
phone: "859-496-2817"
}, {
name: "Lisa Landers",
phone: "901-747-3428"
}, {
name: "Dorothy H. Spencer",
phone: "573-394-9254"
}];
Agora que temos alguns dados que queremos renderizar, vamos configurar alguma marcação. Se quisermos algum estilo pronto para uso, podemos usar algumas das diretivas que vêm com os itens da lista.
Vejamos como podemos usar alguns deles no próximo exemplo:
<!--contacts.component.html-->
<igx-list>
<igx-list-item isHeader="true">
Contacts
</igx-list-item>
<igx-list-item *ngFor="let contact of contacts">
<h4 igxListLineTitle>{{ contact.name }}</h4>
<p igxListLineSubTitle>{{ contact.phone }}</p>
</igx-list-item>
</igx-list>
Ambas as diretivas igxListLineTitle e igxListLineSubTitle dão aos itens da nossa lista uma aparência padrão.
Depois de tudo isso, nossa lista Angular deve ficar assim:
Adding Avatar and Icons
Podemos usar alguns dos nossos outros componentes em conjunto com o componente IgxList para enriquecer a experiência e adicionar alguma funcionalidade. Podemos ter um avatar de imagem legal à esquerda dos valores de nome e telefone. Além disso, podemos adicionar um ícone de estrela à direita deles para permitir que o usuário favorite um contato. Para fazer isso, vamos pegar os módulos IgxAvatar e IgxIcon e importá-los em nosso arquivo app.module.ts.
// app.module.ts
...
import {
IgxListModule,
IgxAvatarModule,
IgxIconModule
} from 'igniteui-angular';
// import { IgxListModule, IgxAvatarModule, IgxIconModule } from '@infragistics/igniteui-angular'; for licensed package
@NgModule({
...
imports: [..., IgxAvatarModule, IgxIconModule],
})
export class AppModule {}
Em seguida, precisamos adicionar mais algumas informações ao nosso objeto de contato, como uma fonte photo para nosso avatar e uma propriedade isFavorite para indicar o status favorito do contato.
// contacts.component.ts
public contacts = [{
name: 'Terrance Orta',
phone: '770-504-2217',
photo: 'https://randomuser.me/api/portraits/men/27.jpg',
isFavorite: false
}, {
name: 'Richard Mahoney',
phone: '423-676-2869',
photo: 'https://randomuser.me/api/portraits/men/1.jpg',
isFavorite: true
}, {
name: 'Donna Price',
phone: '859-496-2817',
photo: 'https://randomuser.me/api/portraits/women/50.jpg',
isFavorite: false
}, {
name: 'Lisa Landers',
phone: '901-747-3428',
photo: 'https://randomuser.me/api/portraits/women/3.jpg',
isFavorite: false
}, {
name: 'Dorothy H. Spencer',
phone: '573-394-9254',
photo: 'https://randomuser.me/api/portraits/women/67.jpg',
isFavorite: true
}];
Legal, agora vamos atualizar o template para nossa lista de contatos para mostrar o avatar e o ícone. Novamente, podemos fazer isso usando algumas das diretivas de lista.
<!--contacts.component.html-->
<igx-list>
<igx-list-item isHeader="true">
Contacts
</igx-list-item>
<igx-list-item #item *ngFor="let contact of contacts;">
<igx-avatar igxListThumbnail [src]="contact.photo" shape="circle"></igx-avatar>
<h4 igxListLineTitle>{{ contact.name }}</h4>
<p igxListLineSubTitle class="phone">{{ contact.phone }}</p>
<span igxListLine>Lorem ipsum dolor sit amet, consectetur adipisicing elit. Dicta, laborum.</span>
<igx-icon igxListAction [color]="contact.isFavorite ? 'orange' : 'lightgray'" (click)="toggleFavorite(item)">star</igx-icon>
</igx-list-item>
</igx-list>
igxListThumbnaildeve ser usado se precisarmos adicionar algum tipo de mídia no início dos itens da nossa lista. A diretiva envolverá o elemento alvo no nosso caso igx-avatar em um contêiner que fornecerá alguma posição e espaçamento padrão.igxListActiondeve ser usado para itens de lista que tenham algum tipo de ação ou metadados, por exemplo, switch, radio-button, checkbox, etc. No nosso caso, a ação será representada por umigx-icon. Novamente, a diretiva envolverá o elemento alvo em um contêiner que terá a posição e o espaçamento corretos.igxListLinedeve ser usado se precisarmos de algum texto entreigxListThumbnaileigxListActionA diretiva garantirá que a posição, o espaçamento e o alinhamento do texto ficarão ótimos com as outras duas diretivas ao redor.
Em seguida, ouvimos um evento de clique no componente IgxIcon para alternar a propriedade isFavorite em nosso objeto de contato.
// contacts.component.ts
...
toggleFavorite(item: IgxListItem) {
const contact = this.contacts[item.index - 1];
contact.isFavorite = !contact.isFavorite;
}
Vamos também permitir que o usuário escolha o tamanho da lista usando a propriedade personalizada CSS--ig-size. Faremos isso importando o IgxButtonGroupModule e usando o IgxButtonGroup para exibir todos os valores de tamanho. Dessa forma, sempre que um for selecionado, atualizaremos o tamanho da lista.
// app.module.ts
...
import { IgxButtonGroupModule } from 'igniteui-angular';
// import { IgxButtonGroupModule } from '@infragistics/igniteui-angular'; for licensed package
@NgModule({
imports: [..., IgxButtonGroupModule]
})
<!--contacts.component.html-->
<igx-buttongroup [values]="sizes" (selected)="selectSize($event)"></igx-buttongroup>
...
<igx-list>
...
</igx-list>
// contacts.component.ts
public size = 'large';
public sizes;
public ngOnInit() {
this.sizes = [
{ label: 'large', selected: this.size === 'large', togglable: true },
{ label: 'medium', selected: this.size === 'medium', togglable: true },
{ label: 'small', selected: this.size === 'small', togglable: true }
];
}
public selectSize(event: any) {
this.size = this.sizes[event.index].label;
}
@HostBinding('style.--ig-size')
protected get sizeStyle() {
return `var(--ig-size-${this.size})`;
}
E aqui está o resultado de todo esse trabalho:
List Items Panning
Agora que temos uma lista Angular tão bonita com contatos e seus números de telefone, por que não implementamos uma habilidade de chamar um contato? O IgxList tem a solução perfeita para isso - lista de itens de panning. Para fazer isso, você tem que implementar os seguintes passos:
- Habilite o panning usando as propriedades
allowLeftPanninge/ouallowRightPanning - Definir modelo(s) para a panorâmica esquerda e/ou direita
- Manipule os eventos de panorâmica do item da lista e execute a ação desejada
O exemplo a seguir demonstra como lidar com o panning esquerdo e direito. O manipulador de eventos para o panning direito mostra uma mensagem toast. O manipulador de eventos para o panning esquerdo exclui um item da IgxList.
Note
Observe que a remoção de itens da lista é uma tarefa de aplicativo. O IgxList em si não pode remover itens da fonte de dados porque o IgxList não tem referência à fonte de dados.
Aqui está o código HTML do exemplo:
<!-- contacts.component.html -->
<igx-list [allowLeftPanning]="true" [allowRightPanning]="true"
(leftPan)="leftPanPerformed($event)" (rightPan)="rightPanPerformed($event)">
<ng-template igxListItemLeftPanning>
<div class="listItemLeftPanningStyle">
<igx-icon [color]="white" style="margin-left:10px">delete</igx-icon>Delete
</div>
</ng-template>
<ng-template igxListItemRightPanning>
<div class="listItemRightPanningStyle">
<igx-icon [color]="white" style="margin-right:10px">call</igx-icon>Dial
</div>
</ng-template>
<igx-list-item isHeader="true">Contacts</igx-list-item>
<igx-list-item #item *ngFor="let contact of contacts">
<igx-avatar igxListThumbnail [src]="contact.photo" shape="circle"></igx-avatar>
<h4 igxListLineTitle>{{ contact.name }}</h4>
<p igxListLineSubTitle class="phone">{{ contact.phone }}</p>
<igx-icon igxListAction [color]="contact.isFavorite ? 'orange' : 'lightgray'" (click)="toggleFavorite(item)">star</igx-icon>
</igx-list-item>
</igx-list>
<igx-toast #toast></igx-toast>
O exemplo acima usa alguns estilos CSS que podem ser encontrados aqui:
/* contacts.component.css */
igx-icon {
cursor: pointer;
user-select: none;
}
.listItemLeftPanningStyle {
display: flex;
flex-direction: row-reverse;
background-color:orange;
color: white;
width: 100%;
padding-right: 10px;
align-items: center;
}
.listItemRightPanningStyle {
display: flex;
flex-direction: row;
background-color:limegreen;
color: white;
width: 100%;
padding-left: 10px;
align-items: center;
}
E finalmente aqui está o código typescript que manipula os eventos de panorâmica:
// contacts.component.ts
...
@ViewChild('toast')
public toast: IgxToastComponent;
public rightPanPerformed(args) {
args.keepItem = true;
this.toast.message = 'Dialing ' + this.contacts[args.item.index - 1].name;
this.toast.open();
}
public leftPanPerformed(args) {
args.keepItem = false;
setTimeout((idx = args.item.index - 1) => {
this.toast.message = 'Contact ' + this.contacts[idx].name + ' removed.';
this.toast.open();
this.contacts.splice(idx, 1);
}, 500);
}
...
Note
Ao fazer o panning de itens de lista, há um limite que deve ser atingido para que os eventos de panning sejam emitidos. Você pode alterar o limite usando a propriedade panEndTriggeringThreshold do IgxList. Por padrão, essa propriedade tem um valor de 0,5, o que significa 50% da largura do item da lista.
Agora tente você mesmo analisar os itens da lista:
Angular filter list
Nossa lista está ótima, mas não seria ainda melhor se pudéssemos procurar contatos por nome? Podemos fazer isso facilmente usando nosso pipe de filtragem. Vamos fazer isso.
Vamos primeiro adicionar um campo de entrada no topo do nosso modelo de componente Angular e vinculá-lo a uma propriedade em nosso componente chamada searchContact:
<!--contacts.component.html-->
<igx-input-group type="search" class="search">
<igx-prefix>
<igx-icon>search</igx-icon>
</igx-prefix>
<input #search igxInput placeholder="Search Contacts" [(ngModel)]="searchContact">
<igx-suffix *ngIf="search.value.length > 0" (click)="searchContact = null">
<igx-icon>clear</igx-icon>
</igx-suffix>
</igx-input-group>
É hora de importar o IgxFilterModule e o IgxInputGroupModule em nosso arquivo app.module.ts e IgxFilterOptions em nosso componente de contatos:
// app.module.ts
...
import { IgxFilterModule, IgxInputGroupModule } from 'igniteui-angular';
// import { IgxFilterModule, IgxInputGroupModule } from '@infragistics/igniteui-angular'; for licensed package
@NgModule({
imports: [..., IgxFilterModule, IgxInputGroupModule]
})
// contacts.component.ts
...
import { IgxFilterOptions } from 'igniteui-angular';
// import { IgxFilterOptions } from '@infragistics/igniteui-angular'; for licensed package
@Component({...})
export class ContactListComponent {
public searchContact: string;
...
get filterContacts(): IgxFilterOptions {
const fo = new IgxFilterOptions();
fo.key = 'name';
fo.inputValue = this.searchContact;
return fo;
}
}
Após importar o IgxFilterOptions, precisamos registrar um novo método getter que retornará as opções de filtragem a serem usadas pelo pipe sempre que a propriedade searchContact for atualizada. Para que o filtro funcione, precisamos registrar uma key para filtrar o objeto de contato. No nosso caso, seria o name de cada contato. A segunda propriedade que precisa ser registrada no objeto IgxFilterOptions é o valor que devemos verificar ao comparar nosso nome de contato. Esta seria a propriedade searchContact que vinculamos ao campo de entrada acima da nossa lista de contatos.
Por fim, precisamos aplicar o pipe de filtragem aos nossos dados de contatos antes de podermos usá-lo. Então, em nosso modelo, simplesmente adicionamos:
<!--contacts.component.html-->
<igx-list-item *ngFor="let contact of contacts | igxFilter: filterContacts; let i = index">
...
</igx-list-item>
List Item Selection
Como você provavelmente já notou, itens de lista não fornecem estados de seleção. No entanto, se seu aplicativo requer que sua lista mantenha o controle de qual item é selecionado, nós lhe damos um exemplo de como isso pode ser alcançado. Tudo o que você precisa fazer é manter o controle do estado em algum lugar em seu componente, ou nos dados aos quais a lista está vinculada.
Aqui está um exemplo, no qual aplicamos uma cor de fundo à lista de acordo com a cor secundária 500 do tema, com base no rastreamento de estado proveniente dos dados aos quais a lista está vinculada:
O que estamos fazendo é adicionar uma propriedade selected adicional a cada membro de dados, cujo padrão é false. Ao clicar no item da lista, estamos redefinindo todas as propriedades selected na coleção de dados e definindo a correspondente ao item clicado como true. Com base na propriedade selecionada, estamos aplicando uma classe css ao item da lista que dá a ele o plano de fundo selecionado.
<igx-list>
<igx-list-item isHeader="true">Contacts</igx-list-item>
<igx-list-item [ngClass]="contact.selected ? 'selected' : ''"
(click)="selectItem(contact)"
*ngFor="let contact of contacts | igxFilter: filterContacts;">
<igx-avatar igxListThumbnail [src]="contact.photo" shape="circle"></igx-avatar>
<span igxListLineTitle>{{ contact.name }}</span>
<span igxListLineSubTitle>{{ contact.phone }}</span>
<igx-icon igxListAction [style.color]="contact.isFavorite ? 'orange' : 'lightgray'" (click)="toggleFavorite(contact, $event)">star</igx-icon>
</igx-list-item>
</igx-list>
public selectItem(item) {
if (!item.selected) {
this.contacts.forEach(c => c.selected = false);
item.selected = true;
}
}
.selected {
background-color: hsla(var(--igx-secondary-500))
}
Chat Component
O exemplo a seguir demonstra como criar um componente de bate-papo simples usando IgxList.
Applying theme to the list component
Vamos ver como podemos mudar o fundo da nossa lista. Primeiro precisamos importar index.scss para o nosso arquivo .scss do componente.
@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 list-theme e aceita o parâmetro $background.
$my-list-theme: list-theme(
$background: #0568ab
);
Dê uma olhada na seção list-theme para obter uma lista completa de parâmetros disponíveis para estilizar a lista.
A última etapa é incluir os temas recém-criados.
@include css-vars($my-list-theme);
O resultado é o seguinte:
Para uma lista completa de parâmetros que você pode alterar para o componente de lista, consulte: Estilos IgxListComponent
API References
Neste artigo, cobrimos muito terreno com o componente de lista Angular. Criamos uma lista de itens de contato. Usamos alguns componentes adicionais Ignite UI for Angular dentro dos nossos itens de lista, como avatares e ícones. Criamos alguns layouts de itens personalizados e os estilizamos. Por fim, adicionamos filtragem de lista. O componente de lista tem mais algumas APIs para explorar, que estão listadas abaixo.
Componentes Angular adicionais que foram usados:
- API do componente IgxAvatar
- Estilos de componentes IgxAvatar
- API do IgxIconComponent
- Estilos IgxIconComponent
Theming Dependencies
Additional Resources
Nossa comunidade é ativa e sempre acolhedora para novas ideias.
GitHub