syncfusion-angular-treeview

在 Angular 中实现 TreeView

TreeView 组件以树状结构显示层级数据，并内置支持复选框、拖放、就地编辑、多选、筛选、排序、模板和键盘导航等交互功能。它非常适合显示文件系统、组织结构图、类别层级、导航菜单以及任何嵌套数据结构。

何时使用此技能

• 构建层级 UI：显示父子数据关系
• 文件／文件夹浏览器：显示可展开／折叠的目录结构
• 导航结构：创建菜单系统或网站层级
• 数据组织：显示分类或嵌套数据
• 交互式选择：实现多选或基于复选框的选择
• 拖放界面：通过拖动节点重新组织树数据
• 搜索／筛选功能：在大型树结构中查找节点
• 自定义外观：按层级设置节点样式或使用模板

导航指南

选择下方的任务，前往相应的参考文档：

入门

📄 阅读： references/getting-started.md

何时阅读：首次设置 TreeView、安装包、导入模块、初始化基本组件、导入 CSS、选择主题或创建第一个树时。

数据绑定与层级结构

📄 阅读： references/data-binding.md

何时阅读：将数据源连接到 TreeView、绑定层级或自引用数据、使用 DataManager、从远程 API 加载数据、实现延迟加载（按需加载）或动态更新树数据时。

节点选择与复选框

📄 阅读： references/node-selection.md

何时阅读：启用复选框、管理复选框状态（选中／未选中／三态）、实现多选或单选、使用选择事件、获取选中节点 ID、禁用复选框或移除父节点复选框时。

节点编辑与操作

📄 阅读： references/node-editing.md

何时阅读：启用就地编辑、以编程方式添加／删除／更新节点、验证编辑后的文本、移动节点或使用节点操作方法（addNodes、removeNodes、updateNode、moveNodes）时。

拖放

📄 阅读： references/drag-and-drop.md

何时阅读：启用拖放功能、限制在特定节点上执行放置、处理拖动事件、自定义放置指示器或阻止无效操作时。

节点模板与样式

📄 阅读： references/templating.md

何时阅读：创建自定义节点模板、使用动态图标、按层级设置节点样式、自定义展开／折叠图标、显示工具提示、处理多行节点或自定义 CSS 时。

筛选与排序

📄 阅读： references/filtering-sorting.md

何时阅读：按文本筛选节点、实现搜索功能、全局或按层级排序节点，或整理树的显示顺序时。

上下文菜单集成

📄 阅读： references/context-menu.md

何时阅读：为节点操作添加上下文菜单、处理右键操作、通过菜单实现添加／编辑／删除，或创建自定义菜单项时。

无障碍、进阶功能与 API 迁移

📄 阅读： references/accessibility-advanced.md

何时阅读：实现键盘导航（方向键、Enter、Space）、ARIA 属性和无障碍合规、RTL（从右到左）支持、获取子节点、手风琴行为、使用进阶方法、从 EJ1 迁移到 EJ2 或优化性能时。

快速入门示例

以下是一个使用静态层级数据的最简 TreeView 实现：

import { Component } from '@angular/core';
import { TreeViewModule } from '@syncfusion/ej2-angular-navigations';
import { FormsModule } from '@angular/forms';

@Component({
  selector: 'app-tree-view',
  standalone: true,
  imports: [FormsModule, TreeViewModule],
  template: `
    <ejs-treeview 
      id="treeView"
      [fields]="treeFields"
      [allowMultiSelection]="true">
    </ejs-treeview>
  `
})
export class TreeViewComponent {
  // Hierarchical data structure
  treeData = [
    {
      id: '01',
      name: 'Documents',
      hasChild: true,
      expanded: true,
      subChild: [
        { id: '01-01', name: 'Work Files' },
        { id: '01-02', name: 'Personal' }
      ]
    },
    {
      id: '02',
      name: 'Downloads',
      hasChild: true,
      subChild: [
        { id: '02-01', name: 'Images' },
        { id: '02-02', name: 'Videos' }
      ]
    }
  ];

  // Field mapping configuration
  treeFields = {
    dataSource: this.treeData,
    id: 'id',
    text: 'name',
    child: 'subChild',
    hasChildren: 'hasChild',
    expanded: 'expanded'
  };
}

TreeView 的关键方法

方法	用途
addNodes(nodes, target?, index?, preventTargetExpand?)	在目标位置添加节点集合
removeNodes(nodeIds)	按 ID 移除节点
updateNode(target, newText)	替换节点文本（需要启用 allowEditing）
moveNodes(sourceNodes, target, index?, preventTargetExpand?)	将节点移动到新的父节点和索引位置
getTreeData(nodeId?)	获取所有树数据或特定节点数据
getAllCheckedNodes()	获取所有已选中节点的 ID，包括已加载或未加载的子节点
checkAll(nodes?)	选中所有或指定节点
uncheckAll(nodes?)	取消选中所有或指定节点
beginEdit(nodeId)	开始编辑节点
expandAll(nodes?, level?, excludeHiddenNodes?, preventAnimation?)	展开所有或指定节点，可按层级展开
collapseAll(nodes?, level?, excludeHiddenNodes?)	折叠所有或指定节点，可按层级折叠
ensureVisible(nodeId)	滚动以显示节点
disableNodes(nodeIds)	禁用指定节点
enableNodes(nodeIds)	启用指定节点
getNode(nodeId)	获取节点的 HTML 元素
destroy()	销毁 TreeView 组件

TreeView 的关键事件

事件	触发时机
created	创建 TreeView 组件时
dataBound	数据源绑定完成时
dataSourceChanged	树数据被修改（添加／移除／更新）时
nodeClicked	用户点击节点时
nodeSelected	选中节点时
nodeSelecting	选中节点之前（可阻止）
nodeChecked	复选框状态改变时
nodeChecking	复选框状态改变之前（可阻止）
nodeExpanding	展开节点之前
nodeExpanded	节点展开时
nodeCollapsing	折叠节点之前
nodeCollapsed	节点折叠时
nodeEditing	编辑节点文本之前
nodeEdited	节点文本编辑之后
nodeDragStart	拖动操作开始时
nodeDragging	正在拖动节点时
nodeDragStop	拖动结束、放置之前
nodeDropped	成功放置节点时
drawNode	渲染每个节点之前（自定义外观）
keyPress	用户按下键盘按键时
destroyed	TreeView 组件销毁时

常见模式

模式 1：基于复选框的选择

启用复选框，以支持多选和分层复选框状态：

treeFields = {
  dataSource: this.treeData,
  id: 'id',
  text: 'name',
  child: 'subChild',
  hasChildren: 'hasChild'
};

showCheckBox = true;  // Enable checkboxes
autoCheck = true;     // Parent/child auto-check

模式 2：支持拖放的文件浏览器

创建可交互的文件浏览器，以便重新组织节点：

<ejs-treeview 
  [fields]="treeFields"
  [allowDragAndDrop]="true"
  [allowMultiSelection]="true"
  (nodeDragging)="onNodeDragging($event)"
  (nodeDropped)="onNodeDropped($event)">
</ejs-treeview>

模式 3：搜索和筛选

实现树节点的实时筛选：

<input 
  type="text" 
  (keyup)="filterTree($event.target.value)" 
  placeholder="Search nodes...">

<ejs-treeview 
  #treeView
  [fields]="filteredFields">
</ejs-treeview>

模式 4：可编辑树

启用节点的就地编辑和验证：

<ejs-treeview 
  [fields]="treeFields"
  [allowEditing]="true"
  (nodeEditing)="onNodeEditing($event)"
  (nodeEdited)="onNodeEdited($event)">
</ejs-treeview>

TreeView 的关键属性

属性	类型	用途
fields	Object	配置数据源映射（id、text、child、parentID、hasChildren、expanded、isChecked 等）
dataSource	Array	层级或扁平数据数组
allowMultiSelection	Boolean	启用多节点选择
showCheckBox	Boolean	在节点前显示复选框
autoCheck	Boolean	选中父节点时自动选中子节点（默认值：true）
allowDragAndDrop	Boolean	启用拖放功能
allowEditing	Boolean	启用节点原位编辑
loadOnDemand	Boolean	仅在展开父节点时加载子节点（默认值：true）
sortOrder	String	排序顺序：'Ascending'、'Descending' 或 'None'
cssClass	String	应用自定义 CSS 类以设置样式
enableRtl	Boolean	启用从右到左的布局支持
enablePersistence	Boolean	保存和恢复 TreeView 状态（展开的节点、选择项）
checkedNodes	Array	应选中的节点 ID 数组
selectedNodes	Array	应选中的节点 ID 数组
nodeTemplate	Template	用于渲染节点的自定义模板
animation	Object	配置展开/折叠动画
allowKeyboardNavigation	Boolean	启用键盘导航（默认值：true）

常见用例

组织结构图：显示具有父子关系的员工层级，并使用自定义模板展示职位。

文件/文件夹浏览器：显示目录结构，并支持通过拖放在文件夹之间移动文件。

类别导航：展示多级产品类别，并使用复选框进行筛选和多选。

设置菜单：按主题组织层级偏好设置或配置选项。

知识库：展示嵌套的文档主题，并支持搜索和展开/折叠导航。

参考文件

• getting-started.md - 安装、设置和基本初始化
• data-binding.md - 数据源、层级结构、远程数据和延迟加载
• node-selection.md - 复选框、多选和选择事件
• node-editing.md - 编辑、添加、移除和更新节点
• drag-and-drop.md - 拖放配置和限制
• templating.md - 自定义模板、图标、样式和工具提示
• filtering-sorting.md - 筛选、搜索和排序功能
• context-menu.md - 上下文菜单集成和节点操作
• accessibility-advanced.md - 键盘导航、ARIA、RTL 和高级方法

---

后续步骤：

1. 从上方的导航指南中选择用例
2. 阅读相关参考文件
3. 根据你的数据结构调整代码示例
4. 使用你的数据源进行测试