Visão geral do componente de árvore Angular

O componente de árvore Angular permite que os usuários representem dados hierárquicos em uma estrutura de exibição de árvore com relacionamentos pai-filho, bem como definam a estrutura estática de exibição de árvore sem um modelo de dados correspondente. Seu objetivo principal é permitir que os usuários finais visualizem e naveguem dentro de estruturas de dados hierárquicas. O componente de árvore de Ignite UI for Angular também fornece recursos de carga sob demanda, ativação de itens, seleção em cascata de itens de dois estados e três estados por meio de caixas de seleção integradas, navegação por teclado integrada e muito mais.

Angular Tree Example

Neste exemplo básico de árvore Angular, você pode ver como definir um igx-tree e seus nós especificando a hierarquia de nós e iterando por meio de um conjunto de dados hierárquico.

Getting Started with Ignite UI for Angular Tree

Para começar a usar o componente Ignite UI for Angular Tree, 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.

A próxima etapa é importar o IgxTreeModule arquivo em seu app.module.

// app.module.ts

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

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

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

// home.component.ts

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

@Component({
    selector: 'app-home',
    template: `
    <igx-tree>
        <igx-tree-node>
            Angular Libraries
            <igx-tree-node>Ignite UI for Angular</igx-tree-node>
            <igx-tree-node>Angular Material</igx-tree-node>
        </igx-tree-node>
        <igx-tree-node>
            Web Component Libraries
            <igx-tree-node>Ignite UI for Web Components</igx-tree-node>
            <igx-tree-node>Open UI 5</igx-tree-node>
        </igx-tree-node>
        <igx-tree-node>
            Blazor Libraries
            <igx-tree-node>Ignite UI for Blazor</igx-tree-node>
        </igx-tree-node>
    </igx-tree>
    `,
    styleUrls: ['home.component.scss'],
    standalone: true,
    imports: [IGX_TREE_DIRECTIVES]
    /* or imports: [IgxTreeComponent, IgxTreeNodeComponent] */
})
export class HomeComponent {}

Agora que temos o módulo ou as diretivas Ignite UI for Angular Tree importados, vamos começar com uma configuração básica do igx-tree e seus nós.

Using the Angular Tree

IgxTreeNodesComponent é a representação de cada nó que pertence ao IgxTreeComponent.
Os nós fornecem propriedades desativadas, ativas, selecionadas e expandidas, que oferecem a oportunidade de configurar os estados do nó de acordo com sua necessidade. data pode ser usada para adicionar uma referência à entrada de dados que o nó representa. A associação [data] é necessária para pesquisar através de nós usando IgxTreeComponent.findNodes().

Declaring a tree

Os nós podem ser declarados usando uma das seguintes abordagens.

Declarando a árvore e seus nós especificando a hierarquia de nós e iterando por meio de um conjunto de dados

<igx-tree>
	<igx-tree-node *ngFor="let node of data" [data]="node" [expanded]="isNodeExpaded(node)" [selected]="isNodeSelected(node)">
		{{ node.text }}
		<img [src]="node.image" [alt]="node.imageAlt" />
		<igx-tree-node *ngFor="let child of node.children" [data]="child" [expanded]="isNodeExpaded(child)" [selected]="isNodeSelected(child)">
            {{ child.text }}
		</igx-tree-node>
	</igx-tree-node>
</igx-tree>

Os nós podem ser associados a um modelo de dados para que seus estados expandidos e selecionados também sejam refletidos nos dados subjacentes.

<igx-tree (nodeSelection)="handleSelectionEvent($event)">
	<igx-tree-node *ngFor="let node of data" [data]="node" [(expanded)]="node.expanded" [(selected)]="node.selected">
		{{ node.text }}
		<img [src]="node.image" [alt]="node.imageAlt" />
		<igx-tree-node *ngFor="let child of node.children" [data]="child">
			<a igxTreeNodeLink [href]="child.url" target="_blank">
                {{ child.text }}
            </a>
		</igx-tree-node>
	</igx-tree-node>
</igx-tree>

Declarando uma árvore criando nós estáticos não ligados

Para renderizar uma árvore, você não precisa necessariamente de um conjunto de dados - nós individuais podem ser criados sem um modelo de dados subjacente:

<igx-tree>
	<igx-tree-node [expanded]="true" [selected]="false">
		I am a parent node 1
		<img src="hard_coded_src.webb" alt="Alt Text" />		
		<igx-tree-node [expanded]="true" [selected]="false">
			I am a child node 1
			<igx-tree-node>
				<a igxTreeNodeLink href="https://google.com" target="_blank">
				    I am a child node of the child
				</a>
			</igx-tree-node>
		</igx-tree-node>
	</igx-tree-node>

	<igx-tree-node [expanded]="false" [selected]="false">
		I am a parent node 2
		<img src="hard_coded_src.webb" alt="Alt Text" />
        <igx-tree-node [expanded]="false" [selected]="false">
			I am a child node 1
		</igx-tree-node>
	</igx-tree-node>

    <igx-tree-node [selected]="false" [disabled]="true">
		I am a parent node 3
	</igx-tree-node>
</igx-tree>

Nodes with links

Quando um nó deve renderizar um link, a IgxTreeNodeLink diretiva deve ser adicionada à <a> tag. Isso garantirá que a função aria adequada seja atribuída aos elementos DOM do nó.

<igx-tree>
	<igx-tree-node *ngFor="let node of data" [data]="node" [expanded]="isNodeExpaded(node)" [selected]="isNodeSelected(node)">
		{{ node.text }}
		<img [src]="node.image" [alt]="node.imageAlt" />
		<igx-tree-node *ngFor="let child of node.children" [data]="child">
            <a igxTreeNodeLink [href]="child.url" target="_blank">
                {{ child.text }}
            </a>
		</igx-tree-node>
	</igx-tree-node>
</igx-tree>

Node Interactions

IgxTreeNodeComponent pode ser expandido ou recolhido:

clicando no indicador de expansão do nó (comportamento padrão).
clicando no nó se a igx-tree propriedade toggleNodeOnClick estiver definida como true.

<igx-tree [toggleNodeOnClick]="true">
	<igx-tree-node *ngFor="let node of data" [data]="node">
		{{ node.text }}
		<igx-tree-node *ngFor="let child of node.children" [data]="child">
                {{ child.text }}
		</igx-tree-node>
	</igx-tree-node>
</igx-tree>

Por padrão, vários nós podem ser expandidos ao mesmo tempo. Para alterar esse comportamento e permitir a expansão de apenas um branch por vez, a propriedade singleBranchExpand pode ser habilitada. Dessa forma, quando um nó é expandido, todas as outras ramificações já expandidas no mesmo nível serão recolhidas.

<igx-tree [singleBranchExpand]="true">
	<igx-tree-node *ngFor="let node of data" [data]="node">
		{{ node.text }}
		<igx-tree-node *ngFor="let child of node.children" [data]="child">
                {{ child.text }}
		</igx-tree-node>
	</igx-tree-node>
</igx-tree>

Além disso, o IgxTree fornece os seguintes métodos de API para interações de nó:

expandir- expande o nó com animação.
collapse- recolhe o nó com animação.
Alternar- Alterna o estado de expansão do nó com animação.
collapseAll- recolhe os nós especificados com animação. Se nenhum nó for passado, recolhe todos os nós pai.
expandAll- define os nós especificados como expandidos com animação. Se nenhum nó for passado, expandirá todos os nós pai.
deselectAll- desmarca todos os nós. Se uma matriz de nós for passada, desmarcará apenas os nós especificados. Não emite o evento nodeSelection.

Finding Nodes

Você pode encontrar um nó específico em um IgxTree usando o método findNodes. Ele retorna uma matriz de nós, que correspondem aos dados especificados. Ao localizar nós em cenários de estrutura de dados mais complexos, como chaves primárias compostas, você pode passar uma função de comparador personalizada para especificar os critérios para localizar nós com base nos dados.

<igx-tree>
	<igx-tree-node *ngFor="let node of data" [data]="node" [expanded]="isNodeExpaded(node)" [selected]="isNodeSelected(node)">
		{{ node.text }}
		<img [src]="node.image" alt="node.imageAlt" />
		<igx-tree-node *ngFor="let child of node.children" [data]="child" [expanded]="isNodeExpaded(child)" [selected]="isNodeSelected(child)">
            {{ child.text }}
		</igx-tree-node>
	</igx-tree-node>
</igx-tree>

export class MyTreeViewComponent {
  public data: { [key: string]: any, valueKey: string } = MY_DATA;
  @ViewChild(IgxTreeComponent, { read: IgxTreeComponent })
  public tree;

  findNode(valueKey: string) {
    const comparer: IgxTreeSearchResolver =
      (data: any, node: IgxTreeNodeComponent) => node.data.valueKey === data;
    const matchingNodes: IgxTreeNode<{ [key: string]: any, valueKey: string }>[] = this.tree.findNodes(valueKey, comparer);
  }
}

Templating

Para criar um modelo reutilizável para seus nós, declare <ng-template> within igx-tree.

<igx-tree>
    <igx-tree-node *ngFor="let node of data" [data]="node">
        <ng-container *ngTemplateOutlet="#nodeTemplate; context: { $implicit: node }"></ng-container>
        <igx-tree-node *ngFor="let child of node.ChildCompanies" [data]="child">
            <ng-container *ngTemplateOutlet="#nodeTemplate; context: { $implicit: child}"></ng-container>
        </igx-tree-node>
    </igx-tree-node>
    <ng-template #nodeTemplate let-data>
        <div class="node-header company">
            <igx-icon class="company__logo">{{ data.Logo }}</igx-icon>
            <div class="company__name">{{ data.CompanyName }}</div>
        </div>
    </ng-template>
</igx-tree>

Além disso, usando a entrada expandIndicator, você tem a capacidade de definir um modelo personalizado a ser usado para renderizar os indicadores de expansão/recolhimento dos nós.

<igx-tree>
    <igx-tree-node *ngFor="let node of data" [data]="node">
    </igx-tree-node>
    <ng-template igxTreeExpandIndicator let-expanded>
        <igx-icon>{{ expanded ? 'expand_less' : 'expand_more' }}</igx-icon>
    </ng-template>
</igx-tree>

Angular Tree Selection

Para configurar a seleção de nó no igx-tree, você só precisa definir sua propriedade selection. Essa propriedade aceita os três modos a seguir: Nenhum, Biestado e Cascata. Abaixo, veremos cada um deles com mais detalhes.

None

Por padrão, a igx-tree seleção de nó está desativada. Os usuários não podem selecionar ou desmarcar um nó por meio da interação da interface do usuário, mas essas ações ainda podem ser concluídas por meio do método de API fornecido.

Bi-State

Para habilitar a seleção de nó de biestado, igx-tree basta definir a propriedade de seleção como BiEstado. Isso renderizará uma caixa de seleção para cada nó. Cada nó tem dois estados - selecionado ou não. Este modo suporta seleção múltipla.

<igx-tree selection="BiState">
</igx-tree>

Cascading

Para habilitar a seleção de nó em cascata no igx-tree, basta definir a propriedade de seleção como Cascata. Isso renderizará uma caixa de seleção para cada nó.

<igx-tree selection="Cascading">
</igx-tree>

Nesse modo, o estado de seleção de um pai depende inteiramente do estado de seleção de seus filhos. Quando um pai tem alguns filhos selecionados e alguns desmarcados, sua caixa de seleção está em um estado indeterminado.

Angular Tree Checkbox

O componente Árvore Angular fornece suporte interno para caixas de seleção, permitindo que os usuários selecionem mais de um item.

As caixas de seleção TreeView também têm um modo de três estados, que é aplicável somente a nós pai parcialmente selecionados. Nesse modo, um nó pai entrará no estado indeterminado quando alguns, mas não todos os nós filhos forem verificados.

A navegação por teclado no IgxTree fornece uma grande variedade de interações de teclado para o usuário. Essa funcionalidade é habilitada por padrão e permite que os usuários naveguem pelos nós.

A navegação IgxTree é compatível com os padrões de acessibilidade do W3C e conveniente de usar.

Combinações de teclas

Arrow Down- Navega para o próximo nó visível. Marca o nó como ativo. Não faz nada se estiver no ÚLTIMO nó
Ctrl + Arrow Down- Navega para o próximo nó visível. Não faz nada se estiver no ÚLTIMO nó
Arrow Up- Navega até o nó visível anterior. Marca o nó como ativo. Não faz nada se no PRIMEIRO nó
Ctrl + Arrow Up- Navega até o nó visível anterior. Não faz nada se no PRIMEIRO nó
Arrow Left- em um nó pai expandido, recolhe-o. Se estiver em um nó filho, move-se para seu nó pai.
Arrow Right- Em um nó pai expandido, navega até o primeiro filho do nó. Se estiver em um nó pai recolhido, expande-o.
Home- navega para o PRIMEIRO nó
End- navega até o ÚLTIMO nó visível
Tab- navega para o próximo elemento focalizável na página, fora da árvore
Shift + Tab- navega para o elemento focalizável anterior na página, fora da árvore
Space- Alterna a seleção do nó atual. Marca o nó como ativo.
Shift + Space- alterna a seleção de todos os nós entre o ativo e o pressionado Espaço enquanto mantém pressionada a tecla Shift se a seleção estiver ativada
Enter- ativa o nó focado. Se o nó tiver um link, abra o link
*- expande o nó e todos os nós irmãos no mesmo nível

Quando a seleção está ativada, a seleção de nós do usuário final só é permitida por meio da caixa de seleção renderizada. Como ambos os tipos de seleção permitem várias seleções, as seguintes interações de mouse + teclado estão disponíveis:

Click- Quando executado na caixa de seleção Nó, alterna a seleção do nó se a seleção estiver ativada. Caso contrário, focaliza o nó
Shift + Click- quando executado na caixa de seleção do nó, alterna a seleção de todos os nós entre o ativo e o clicado enquanto mantém pressionada a tecla Shift se a seleção estiver ativada

Angular Tree Load On Demand

O Ignite UI for Angular IgxTree pode ser renderizado de forma que exija que a quantidade mínima de dados seja recuperada do servidor para que o usuário possa vê-los o mais rápido possível. Com essa abordagem de carregamento dinâmico de dados, somente depois que o usuário expandir um nó, os filhos desse nó pai específico serão recuperados. Esse mecanismo, também conhecido como Load on Demand, pode ser facilmente configurado para funcionar com qualquer dado remoto.

Demo

Depois que o usuário clica no ícone de expansão, ele é substituído por um indicador de carregamento. Quando a propriedade de carregamento é resolvida para false, o indicador de carregamento desaparece e os filhos são carregados.

Estilização

Usando o Ignite UI for Angular Theming, podemos alterar bastante a aparência da árvore. Primeiro, para que possamos usar as funções expostas pelo mecanismo de tema, precisamos importar o index arquivo 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 tree-theme e passa os parâmetros, que gostaríamos de alterar:

$custom-tree-theme: tree-theme(
  $background-selected: #ffe6cc,
  $background-active: #ecaa53,
  $background-active-selected: #ff8c1a
);

A última etapa é incluir o tema do componente.

@include css-vars($custom-tree-theme);

Demo

Known Issues and Limitations

Limitação	Descrição
Nós de modelo recursivos	O`igx-tree` não suporta a criação recursiva de igx-tree-nodes via template. Saiba mais. Todos os nós devem ser declarados manualmente, o que significa que, se você pretende visualizar uma hierarquia muito profunda, isso afetaria o tamanho do arquivo de modelo. A árvore destina-se a ser usada principalmente como um componente de layout / navegação. Se uma fonte de dados hierárquica com vários níveis de profundidade e dados homogêneos precisar ser visualizada, você poderá usar o IgxTreeGrid
Usando IgxTreeNodes com o antigo View Engine (pré-Ivy)	Há um problema no View Engine do Angular (pré-Ivy) que impede que a árvore seja usada quando`enableIvy: false` está definida em tsconfig.json
Navegação por guias no FireFox	Entrar na árvore por meio da navegação pelo teclado, quando a árvore tiver uma barra de rolagem, focará primeiro o elemento igx-tree-node. Este é o comportamento padrão no FireFox, no entanto, pode ser resolvido colocando um explícito`tabIndex = -1` na árvore.

API References

Additional Resources

Nossa comunidade é ativa e sempre acolhedora para novas ideias.

Visão geral do componente de árvore Angular

Angular Tree Example

Getting Started with Ignite UI for Angular Tree

Using the Angular Tree

Declaring a tree

Nodes with links

Node Interactions

Finding Nodes

Templating

Angular Tree Selection

None

Bi-State

Cascading

Angular Tree Checkbox

Keyboard Navigation

Angular Tree Load On Demand

Demo

Estilização

Demo

Known Issues and Limitations

API References

Additional Resources

Temas