【DevUI】用于表现层级嵌套结构数据的核心Tree 树组件

原创于 2025-12-11 11:24:09 发布 · 811 阅读

30 ·

CC 4.0 BY-SA版权

文章标签：

#DevUI

前言

本文是关于 DevUI Tree 树组件 的详细使用示例与代码说明总结文章。该组件是基于 Angular ^18.0.0 版本，用于展示层次结构数据，并提供了极其丰富的交互功能。
在这里插入图片描述

1. 组件概述

Tree 树组件是 DevUI 中用于表现层级嵌套结构数据的核心组件。它分为两种：

基础树 (<d-tree>)：主要用于数据的层级展示与展开/折叠。
可操作树 (<d-operable-tree>)：在基础树之上，集成了节点勾选、编辑、拖拽、搜索等全套交互功能，是功能最全面的版本。

2. 核心功能与代码示例

2.1 基本用法

这是最简单的树，用于渲染一个静态的层级结构。

<!-- 基本树 -->
<d-tree [tree]="basicData" (nodeSelected)="onNodeSelected($event)"></d-tree>

<!-- 自定义缩进（默认为24px） -->
<d-tree [tree]="basicData" [indent]="‘8px‘"></d-tree>

关键点：

[tree]：绑定树形结构数据。
(nodeSelected) / (nodeToggled)：监听节点选中和展开/折叠事件。
[indent]：控制每一层级的缩进距离。

2.2 可勾选树

使用 <d-operable-tree>，并通过 [checkableRelation] 属性控制复选框的联动逻辑。

<!-- 四种联动关系示例 -->
<d-operable-tree [tree]="data1" [checkableRelation]="‘both‘"></d-operable-tree>
<d-operable-tree [tree]="data2" [checkableRelation]="‘upward‘"></d-operable-tree>
<d-operable-tree [tree]="data3" [checkableRelation]="‘downward‘"></d-operable-tree>
<d-operable-tree [tree]="data4" [checkableRelation]="‘none‘"></d-operable-tree>

联动关系说明：

both（默认）：父子节点状态完全联动。
upward：子节点影响父节点（勾选子节点，父节点变为半选或全选）。
downward：父节点影响子节点。
none：父子节点状态互不影响。

2.3 操作按钮（增删改）

可操作树支持直接在节点上或通过外部按钮进行增、删、改操作。

<d-operable-tree
    #operableTree
    [tree]="data"
    [addable]="true"
    [editable]="true"
    [deletable]="true"
    [beforeDeleteNode]="beforeDeleteNode"
    (nodeEdited)="onNodeEdited($event)">
</d-operable-tree>

<!-- 外部触发操作的按钮 -->
<d-button (click)=“operableTree.addNode(node)”>添加子节点</d-button>
<d-button (click)=“operableTree.editNode(node)”>编辑节点</d-button>
<d-button (click)=“operableTree.deleteNode(node)”>删除节点</d-button>

关键点：

通过 [addable], [editable], [deletable] 启用功能。
使用 beforeAddNode/EditNode/DeleteNode 等回调函数进行操作前的拦截或验证。
可通过模板引用变量（如 #operableTree）获取组件实例，以编程方式调用操作。

2.4 搜索与过滤

结合 d-search 组件和 treeFactory 提供的方法，可以实现实时搜索和高亮过滤。

<d-search [placeholder]=“‘搜索节点...‘" (searchFn)=“onSearch($event)”></d-search>
<d-operable-tree #operableTree [tree]=“data”></d-operable-tree>

在组件类中，需要调用 treeFactory.searchTree 方法来处理搜索逻辑，并更新绑定到树的数据。

2.5 自定义图标与节点模板

这是组件高度可定制化的体现，允许你完全控制节点图标、内容以及操作按钮的样式。

<d-operable-tree [tree]="data">
    <!-- 自定义节点前的图标 -->
    <ng-template #iconTemplate let-node=“node”>
        <i [class]=“getIconClass(node)”></i>
    </ng-template>

    <!-- 自定义整个节点的显示内容 -->
    <ng-template #nodeTemplate let-node=“node”>
        <span [class.highlight]=“node.isActive”>{{ node.title }}</span>
        <span class=“custom-badge”>{{ node.count }}</span>
    </ng-template>
</d-operable-tree>

2.6 可拖拽树

通过 [draggable]=“true” 开启拖拽功能，支持树内节点排序和跨树/外部元素拖拽。

<d-operable-tree
    [tree]="data"
    [draggable]="true"
    [dropType]="‘drag insert‘"
    (nodeOnDrop)=“onDrop($event)”>
</d-operable-tree>

关键属性：

[dropType]：控制拖放类型，如 ‘insert‘（插入）、‘drag insert‘（拖拽插入）等。
(nodeDragStart) / (nodeOnDrop)：监听拖拽开始和结束事件。

2.7 节点懒加载

对于需要动态加载子节点的大型树，可以使用懒加载优化性能。

<d-tree
    [tree]="lazyLoadData"
    (nodeToggled)=“loadChildren($event)”
    [loadingTemplateRef]=“customLoadingTemplate”>
</d-tree>
<ng-template #customLoadingTemplate>
    <div>正在加载...</div>
</ng-template>

关键点：在 (nodeToggled) 事件中判断节点是否为首次展开，并动态获取其子节点数据后更新树。

2.8 大数据量虚拟滚动

当处理成千上万个节点时，开启虚拟滚动可以避免一次性渲染所有DOM，从而保证性能。

<d-operable-tree
    [tree]="hugeData"
    [virtualScroll]="true"
    [virtualScrollHeight]="‘600px‘"
    [minBufferPx]="600"
    [maxBufferPx]="1200">
</d-operable-tree>

3. 高级配置与工具函数

3.1 自定义数据键名

当你的后端数据字段名与组件默认期望的 (id, title, children) 不一致时，可以自定义映射。

<d-operable-tree
    [tree]="customData"
    [treeNodeIdKey]=“'key'"
    [treeNodeTitleKey]=“'label'"
    [treeNodeChildrenKey]=“'items'">
</d-operable-tree>

3.2 使用 `treeFactory` 工具函数

treeFactory 提供了一系列强大的工具函数，用于以编程方式操作树的状态。

import { treeFactory } from ‘ng-devui/tree‘;

// 例如：勾选所有节点
checkAllNodes() {
    const treeInstance = this.operableTree.treeFactory;
    treeInstance.checkAllNodes(true); // true为勾选，false为取消
}

// 根据ID获取、激活、隐藏、禁用特定节点
treeInstance.getNodeById(‘nodeId‘);
treeFactory.activeNodeById(‘nodeId‘);
treeFactory.hideNodeById(‘nodeId‘, true);

这些函数使你无需直接操作原始数据，就能高效地控制树的行为。

4. 功能特性速查表

为了帮助您快速找到所需功能，以下是 Tree 组件核心特性的对比：

功能特性	适用组件	关键属性/方法	说明
基础展示	`<d-tree>`	`[tree]`, `[indent]`	渲染层级结构，可自定义缩进
节点勾选	`<d-operable-tree>`	`[checkableRelation]`	支持四种父子节点勾选联动逻辑
节点操作	`<d-operable-tree>`	`[addable/editable/deletable]`, `before*`回调	支持增、删、改及操作前拦截
搜索过滤	`<d-operable-tree>`	配合 `d-search` 和 `treeFactory.searchTree`	实现关键词搜索与节点过滤
自定义模板	`<d-operable-tree>`	`#iconTemplate`, `#nodeTemplate`	完全自定义图标、节点内容显示
拖拽排序	`<d-operable-tree>`	`[draggable]=“true”`, `[dropType]`	支持树内及跨区域拖拽
懒加载	`<d-tree>`	`(nodeToggled)` 事件, `[loadingTemplateRef]`	动态展开时加载子节点数据
虚拟滚动	`<d-operable-tree>`	`[virtualScroll]=“true”`, `[virtualScrollHeight]`	优化海量节点渲染性能
数据键映射	`<d-operable-tree>`	`[treeNode*Key]`（如 `treeNodeIdKey`）	适配自定义数据结构字段名
编程式控制	`<d-operable-tree>`	`treeFactory` 工具函数	通过API勾选、展开、禁用节点等