Tree

Explora datos jerárquicos con expansión, selección y reordenación opcionales y controladas.

Categoría: Datos y jerarquía
Import: @neural-ui/core/tree
Selector: neu-tree

import { NeuTreeComponent } from '@neural-ui/core/tree';

Uso

nodes aporta registros planos con claves estables y data; hierarchy describe raíces y relaciones de hijos cargados o pendientes. Aplica expandedKeysChange.keys a expandedKeys y selectionChange.selection a selection. childrenRequest identifica el padre pendiente y la petición; la aplicación carga los hijos y sustituye nodes/hierarchy. nodeMove es una propuesta: actualiza hierarchy para aceptarla. El Template recibe data, no el nodo envolvente.

Ejemplos

Prueba esta interacción gestionada por la aplicación. Código incluye los eventos y los datos iniciales.

Buscar carpetas

Área de trabajo

Diseño

Ingeniería

Archivo

Eventos: 0

Prueba y configura

Cambia las opciones públicas, prueba el resultado y consulta el template actualizado. Código contiene la implementación ejecutable completa.

Buscar carpetas

Área de trabajo

Diseño

Ingeniería

Archivo

Eventos: 0

Cargar ramas bajo demanda

searchable

reorderable

Opciones avanzadas · 8

<neu-tree
  [nodes]="nodes()"
  [hierarchy]="hierarchy()"
  [expandedKeys]="expanded()"
  (expandedKeysChange)="
    expanded.set($event.keys); record('expandedKeysChange', $event)
  "
  [selectionMode]="'checkbox'"
  [selection]="selection()"
  (selectionChange)="acceptSelection($event.selection)"
  [searchable]="true"
  [reorderable]="false"
  (nodeAction)="record('nodeAction', $event)"
  (childrenRequest)="requestChildren($event)"
  (nodeMove)="acceptMove($event)"
  [ariaLabel]="'Carpetas de proyectos'"
  [collapseLabel]="'Contraer carpeta'"
  [emptyLabel]="'Sin carpetas'"
  [expandLabel]="'Expandir carpeta'"
  [invalidTreeLabel]="'Datos del árbol no válidos'"
  [retryLabel]="'Reintentar carga'"
  [searchLabel]="'Buscar carpetas'"
></neu-tree>

Estado y datos de esta configuración

Estos valores corresponden a la vista previa actual. Los handlers, imports de Core y templates completos están en Código.

import { signal } from '@angular/core';

export const nodes = signal([
  {
    "key": "workspace",
    "label": "Área de trabajo",
    "data": {
      "name": "Área de trabajo"
    }
  },
  {
    "key": "design",
    "label": "Diseño",
    "data": {
      "name": "Diseño"
    }
  },
  {
    "key": "engineering",
    "label": "Ingeniería",
    "data": {
      "name": "Ingeniería"
    }
  },
  {
    "key": "archive",
    "label": "Archivo",
    "disabled": true,
    "data": {
      "name": "Archivo"
    }
  }
]);

export const hierarchy = signal({
  "revision": 1,
  "roots": [
    "workspace",
    "archive"
  ],
  "children": [
    {
      "parentKey": "workspace",
      "state": "loaded",
      "keys": [
        "design",
        "engineering"
      ]
    }
  ]
});

export const expanded = signal([
  "workspace"
]);

export const selection = signal({
  "mode": "checkbox",
  "keys": []
});

Inputs de datos, callbacks y configuración estructurada

Estos inputs requieren un modelo o función, no un checkbox. Modifica el campo del mismo nombre en el componente de Código y enlázalo al template; los datos que ya usa esta vista previa se muestran en el estado anterior.

hierarchy · NeuTreeHierarchy<K>

En Código: define hierarchy con este tipo y utiliza [hierarchy]="hierarchy" (o hierarchy() si es una signal).

nodes · readonly NeuTreeNode<T, K>[]

En Código: define nodes con este tipo y utiliza [nodes]="nodes" (o nodes() si es una signal).

virtualization · NeuTreeVirtualization | null

En Código: define virtualization con este tipo y utiliza [virtualization]="virtualization" (o virtualization() si es una signal).

Estado y eventos

Accesibilidad y teclado

Las flechas recorren y expanden/contraen nodos; Inicio/Fin alcanza el primer/último nodo visible. Espacio cambia la selección. La reordenación incluye alternativas de teclado cuando está habilitada.

Tecla	Acción
`Tab`	Accede al árbol y a sus controles habilitados.
`ArrowDown / ArrowUp`	Enfoca el siguiente o anterior nodo visible.
`ArrowRight / ArrowLeft`	Expande, entra, contrae o sale de una rama; la dirección horizontal respeta RTL.
`Home`	Enfoca el primer nodo visible.
`End`	Enfoca el último nodo visible.
`Enter`	Activa la selección del nodo enfocado cuando está habilitada.
`Space`	Activa la selección del nodo enfocado cuando está habilitada.

API

Inputs, modelos y Outputs se extraen del paquete Core instalado. Los tipos públicos enlazan a sus definiciones. Los Templates incluyen ejemplos ejecutables.

Inputs

Configura el componente con [propiedad]="valor". Tu aplicación proporciona estos valores; el componente no debe reemplazar el estado que le pasas.

Nombre	Tipo	Por defecto	Uso en el template	Descripción
`ariaLabel`	`string`	`'Tree'`	`[ariaLabel]`	Nombre accesible del árbol.
`collapseLabel`	`string`	`'Collapse node'`	`[collapseLabel]`	Etiqueta accesible del botón en modo expandido.
`emptyLabel`	`string`	`'No nodes available'`	`[emptyLabel]`	Etiqueta de colección vacía. Tradúcela para tu aplicación.
`expandedKeys`	`readonly K[]`	`[]`	`[expandedKeys]`	Claves aplicadas de ramas expandidas. Los cambios de expansión se proponen a la aplicación.
`expandLabel`	`string`	`'Expand node'`	`[expandLabel]`	Etiqueta accesible del botón en modo contraído.
`hierarchy`	`NeuTreeHierarchy<K>`	Obligatorio	`[hierarchy]`	Raíces y relaciones de hijos, con estado loaded/loading/error/unloaded e identidades de revisión.
`indentSize`	`number`	`18`	`[indentSize]`	Sangría horizontal por nivel del árbol en píxeles.
`invalidTreeLabel`	`string`	`'Tree data is invalid'`	`[invalidTreeLabel]`	Texto accesible de diagnóstico si la jerarquía es incoherente.
`nodes`	`readonly NeuTreeNode<T, K>[]`	Obligatorio	`[nodes]`	Registros planos de nodos con clave. hierarchy define por separado las relaciones entre padres e hijos.
`reorderable`	`boolean`	`false`	`[reorderable]`	Permite propuestas de movimiento de nodos; la aplicación sigue gestionando la jerarquía.
`retryLabel`	`string`	`'Retry loading'`	`[retryLabel]`	Etiqueta visible o accesible para reintentar una carga o subida fallida.
`searchable`	`boolean`	`false`	`[searchable]`	Muestra el campo de búsqueda integrado.
`searchLabel`	`string`	`'Search nodes'`	`[searchLabel]`	Etiqueta accesible o texto de ayuda del campo de búsqueda.
`selection`	`NeuTreeSelection<K>`	`{ mode: 'none' }`	`[selection]`	Estado de selección aplicado según su modo: none, single, multiple o checkbox.
`virtualization`	`NeuTreeVirtualization \| null`	`null`	`[virtualization]`	Configuración de la ventana virtual del árbol, o null para renderizado normal.

Outputs

Escucha un evento con (evento)="handler($event)". La tabla indica qué datos recibe tu función y cómo utilizarlos.

Nombre	Valor emitido	Uso en el template	Descripción
`childrenRequest`	`NeuTreeChildrenRequest<K>`	`(childrenRequest)="onChildrenRequest($event)"`	Solicita hijos mediante parentKey, requestId y hierarchyRevision. Carga registros y actualiza nodes/hierarchy.
`expandedKeysChange`	`NeuTreeExpandedKeysChange<K>`	`(expandedKeysChange)="onExpandedKeysChange($event)"`	Propone las próximas claves de ramas. Actualiza expandedKeys para aceptar un cambio controlado.
`nodeAction`	`NeuTreeNodeAction<K>`	`(nodeAction)="onNodeAction($event)"`	Emite la clave estable del nodo activado.
`nodeMove`	`NeuTreeNodeMove<K>`	`(nodeMove)="onNodeMove($event)"`	Propone un movimiento con claves de origen/destino y posición. Sustituye hierarchy para aceptarlo.
`selectionChange`	`NeuTreeSelectionChange<K>`	`(selectionChange)="onSelectionChange($event)"`	Propone la selección, la clave afectada y el origen de la interacción. Aplica payload.selection a selection.

Templates

ng-content proyecta contenido dentro del componente. Los inputs TemplateRef reciben un template; las directivas ng-template identifican templates con un contexto tipado. Una directiva compartida en el entrypoint no es necesariamente un slot de este componente.

Nombre	Mecanismo	Contrato
`NeuTreeNodeDirective`Ver ejemplo	Directiva pública de template	`ng-template[neuTreeNode]`

NeuTreeNodeDirectiveVer ejemplo

Directiva pública de template

ng-template[neuTreeNode]

Declaración

import type { NeuTreeKey } from '@neural-ui/core/tree';

import { NeuTreeNodeDirective } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export declare class NeuTreeNodeDirective<T, K extends NeuTreeKey = string> {
}

Contexto completo

import type { NeuTreeNodeTemplateContext } from '@neural-ui/core/tree';

import { NeuTreeNodeDirective } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
readonly templateRef: TemplateRef<NeuTreeNodeTemplateContext<T, K>>;

Cada ejemplo muestra un template diferente. Alterna entre Demo y Código para consultar su implementación, imports y estado.

NeuTreeNodeDirective

NeuTreeNodeDirective

Buscar carpetas

Área de trabajoNivel 1 · —

DiseñoNivel 2 · —

IngenieríaNivel 2 · —

ArchivoNivel 1 · —

Eventos: 0

Public Types

Abre un tipo para consultar su definición y los campos de sus interfaces.

NeuTreeChildrenRelationTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeChildrenRelation } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export type NeuTreeChildrenRelation<K extends NeuTreeKey> = {
    readonly parentKey: K;
    readonly state: 'unloaded';
} | {
    readonly parentKey: K;
    readonly state: 'loading';
    readonly requestId: number;
} | {
    readonly parentKey: K;
    readonly state: 'loaded';
    readonly keys: readonly K[];
} | {
    readonly parentKey: K;
    readonly state: 'error';
    readonly requestId?: number;
};

NeuTreeChildrenRequestTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeChildrenRequest } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeChildrenRequest<K extends NeuTreeKey> {
  readonly hierarchyRevision: number;
  readonly parentKey: K;
  readonly reason: 'expand' | 'retry';
  readonly requestId: number;
}

NeuTreeExpandedKeysChangeTypeScript

import type { NeuTreeInteractionSource } from '@neural-ui/core/tree';
import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeExpandedKeysChange } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeExpandedKeysChange<K extends NeuTreeKey> {
  readonly expanded: boolean;
  readonly key: K;
  readonly keys: readonly K[];
  readonly source: NeuTreeInteractionSource;
}

NeuTreeHierarchyTypeScript

import type { NeuTreeChildrenRelation } from '@neural-ui/core/tree';
import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeHierarchy } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeHierarchy<K extends NeuTreeKey> {
  readonly children: readonly NeuTreeChildrenRelation<K>[];
  readonly revision: number;
  readonly roots: readonly K[];
}

NeuTreeInteractionSourceTypeScript

import type { NeuTreeInteractionSource } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export type NeuTreeInteractionSource = 'pointer' | 'keyboard';

NeuTreeKeyTypeScript

NeuTreeMovePositionTypeScript

import type { NeuTreeMovePosition } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export type NeuTreeMovePosition = 'before' | 'inside' | 'after';

NeuTreeNodeTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeNode } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeNode<T, K extends NeuTreeKey = string> {
  readonly badge?: string;
  readonly data: T;
  readonly description?: string;
  readonly disabled?: boolean;
  readonly key: K;
  readonly label: string;
}

NeuTreeNodeActionTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeNodeAction } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeNodeAction<K extends NeuTreeKey> {
  readonly key: K;
}

NeuTreeNodeMoveTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';
import type { NeuTreeMovePosition } from '@neural-ui/core/tree';

import type { NeuTreeNodeMove } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeNodeMove<K extends NeuTreeKey> {
  readonly position: NeuTreeMovePosition;
  readonly sourceIndex: number;
  readonly sourceKey: K;
  readonly sourceParentKey: K | null;
  readonly targetIndex: number;
  readonly targetKey: K;
  readonly targetParentKey: K | null;
}

NeuTreeNodeTemplateContextTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeNodeTemplateContext } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeNodeTemplateContext<T, K extends NeuTreeKey = string> {
  readonly $implicit: T;
  readonly disabled: boolean;
  readonly expanded: boolean;
  readonly hasChildren: boolean;
  readonly key: K;
  readonly level: number;
  readonly loading: boolean;
  readonly partial: boolean;
  readonly selected: boolean;
}

NeuTreeSelectionTypeScript

import type { NeuTreeKey } from '@neural-ui/core/tree';

import type { NeuTreeSelection } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export type NeuTreeSelection<K extends NeuTreeKey> = {
    readonly mode: 'none';
} | {
    readonly mode: 'single';
    readonly key: K | null;
} | {
    readonly mode: 'multiple';
    readonly keys: readonly K[];
} | {
    readonly mode: 'checkbox';
    readonly keys: readonly K[];
};

NeuTreeSelectionChangeTypeScript

import type { NeuTreeInteractionSource } from '@neural-ui/core/tree';
import type { NeuTreeKey } from '@neural-ui/core/tree';
import type { NeuTreeSelection } from '@neural-ui/core/tree';

import type { NeuTreeSelectionChange } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeSelectionChange<K extends NeuTreeKey> {
  readonly key: K;
  readonly selection: NeuTreeSelection<K>;
  readonly source: NeuTreeInteractionSource;
}

NeuTreeVirtualizationTypeScript

import type { NeuTreeVirtualization } from '@neural-ui/core/tree';

// Declaración pública (solo referencia)
export interface NeuTreeVirtualization {
  readonly buffer?: number;
  readonly itemSize: number;
  readonly viewportHeight: number;
}

Estilos y tokens

Usa los tokens públicos de la referencia. El diseño del contenedor pertenece a tu aplicación; comprueba el resultado en modo claro y oscuro y en espacios estrechos.

Tokens específicos

Este componente utiliza tokens compartidos del tema en lugar de tokens específicos.

Tokens compartidos utilizados

Sobrescríbelos en un contenedor local para afectar a este ejemplo. Una modificación en :root afecta a los demás componentes que utilizan el mismo token.

Token	Efecto aquí	Otros efectos	Valor / alternativa
`--neu-border`	Bordes normales de controles y celdas	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`rgba(15, 23, 42, 0.08)`
`--neu-focus-ring`	Anillo normal del foco de teclado	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`0 0 0 var(--neu-focus-ring-width) rgba(0, 122, 255, 0.15)`
`--neu-primary`	Color de marca en controles activos y énfasis	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#007aff`
`--neu-primary-dark`	Tono oscuro de marca; texto de Button outline y ghost en el tema claro	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#005fcc`
`--neu-primary-light`	Tono claro de marca; texto de Button outline y ghost en el tema oscuro	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#339dff`
`--neu-surface`	Superficie principal del campo, cabecera o control	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#ffffff`
`--neu-surface-2`	Superficies secundarias y filas alternas	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#f1f5f9`
`--neu-text`	Color del texto principal y de los iconos que lo heredan	Compartido con otros consumidores de Core; limita el cambio a un ámbito.	`#0f172a`