syncfusion-angular-treegrid

Syncfusion Angular TreeGrid

完整指南：如何实现和自定义 Syncfusion Angular TreeGrid 组件，以可视化层次结构数据。

⚠️ 安全与信任边界

• TreeGrid 技能不会执行任何远程数据访问。
• 所有外部 API 交互均由此技能信任边界之外的独立 DataManager 技能处理。

目录

• 何时使用此技能
• 数据结构规则
• 文档导航指南
• 快速入门示例
• 常见模式
• 最佳实践
• 关键属性摘要
• 模块注入

何时使用此技能

在以下情况下使用此技能：

• 以网格格式显示层次结构或树形结构数据
• 实现高级数据操作（排序、筛选、搜索、编辑）
• 为大型数据集配置分页和虚拟滚动
• 添加导出功能（PDF、Excel）
• 使用主题和 CSS 自定义外观
• 处理选择、聚合和状态管理
• 支持移动端／响应式设计
• 实现行／列冻结

数据结构规则

规则 1：层次结构数据必须使用 childMapping

严重程度：🔴 严重——没有此项，网格将无法展开／折叠

要求：

// ✅ REQUIRED - Must match data property name exactly
<ejs-treegrid 
  [dataSource]='data'
  childMapping='subtasks'>  // Property name is case-sensitive
</ejs-treegrid>

// ❌ WRONG - Will not work
<ejs-treegrid 
  [dataSource]='data'>
  
</ejs-treegrid>

数据格式：

// ✅ CORRECT - childMapping matches 'subtasks' property
public data = [
  {
    TaskID: 1,
    TaskName: 'Parent',
    subtasks: [  // Must match childMapping value
      { TaskID: 2, TaskName: 'Child' }
    ]
  }
];

例外情况：对于扁平的父子结构，请使用 idMapping + parentIdMapping：

// Alternative: Flat structure with parent IDs
<ejs-treegrid 
  [dataSource]='flatData'
  idMapping='TaskID'
  parentIdMapping='ParentID'
  hasChildMapping='isParent'>
</ejs-treegrid>

规则 2：数据类型必须匹配

严重程度：🟠 重要——类型不匹配会导致渲染／排序问题

要求：

// ✅ CORRECT - Type matches column definition
public data = [
  {
    TaskID: 1,              // number type
    TaskName: 'Planning',   // string type
    StartDate: new Date(),  // Date object for date columns
  }
];

// Column definition must match data types
<e-columns>
  <e-column field='TaskID' headerText='ID' type='number'></e-column>
  <e-column field='TaskName' headerText='Task' type='text'></e-column>
  <e-column field='StartDate' headerText='Date' type='date' format='yMd'></e-column>
</e-columns>

// ❌ WRONG - Type mismatch
public data = [
  {
    TaskID: '1',            // String instead of number
    StartDate: '02/03/2024' // String instead of Date object
  }
];

文档导航指南

入门与设置

📄 阅读： references/getting-started-guide.md

• 完整的安装与设置说明
• 模块配置
• 项目初始化
• 第一个 TreeGrid 组件

API 快速参考

📄 阅读： references/properties.md

• 通过结构化表格介绍 70 多个属性
• 数据绑定、显示、行为和功能
• 设置对象和模块
• 列属性快速参考

📄 阅读： references/methods.md

• 通过结构化表格介绍 60 多个方法
• 数据管理、选择、展开／折叠
• 筛选、排序、导出、编辑
• DOM 访问和实用方法

📄 阅读： references/events.md

• 通过结构化表格介绍 56 多个事件
• 可取消事件和异步模式
• 数据、操作、选择、编辑事件
• 导出、打印和查询事件

推荐供需要快速查找属性／方法／事件的开发者阅读

数据绑定

📄 阅读： references/data-binding.md

• 本地和远程数据绑定
• ORM 和自定义适配器实现
• 从各种来源加载数据

远程数据适配器

📄 阅读： references/adaptors.md

• 用于后端集成的 7 种适配器类型
• UrlAdaptor、ODataV4Adaptor、WebApiAdaptor、GraphQLAdaptor
• 自定义适配器和 RemoteSaveAdaptor
• 后端配置示例（C#、Node.js）
• 请求／响应格式规范
• 错误处理和适配器比较

Observable 数据

📄 阅读： references/observables.md

• RxJS observable 集成
• 异步数据绑定模式
• 基于 observable 的事件处理
• 异步运算符和管道

列配置

📄 阅读： references/column.md

• 列定义和宽度管理
• 自定义列模板和渲染
• 列重新排序和冻结

列跨越

📄 阅读： references/column-spanning.md

• 多列跨越配置
• 单元格跨列
• 动态跨越计算

命令列

📄 阅读： references/command-column.md

• 带操作按钮的命令列
• 编辑、删除和取消按钮
• 自定义命令实现

列菜单

📄 阅读： references/column-menu.md

• 列标题上下文菜单
• 排序、分组和筛选菜单项
• 自定义列菜单选项

列选择器

📄 阅读： references/column-chooser.md

• 列可见性切换界面
• 动态显示/隐藏列
• 列选择器对话框配置

行配置

📄 阅读： references/row.md

• 行模板和详情行
• 行拖放功能
• 行跨列和自定义设置

单元格级功能

📄 阅读： references/cell.md

• 单元格样式和格式设置
• 单元格模板和工具提示
• 自定义 CSS 和 HTML 内容

模块系统与架构

📄 阅读： references/modules.md

• 模块导入和依赖项
• 必需的服务提供程序
• Angular 版本兼容性
• 库设置和初始化

编辑

📄 阅读： references/editing.md

• 单元格、内联、对话框、行和批量编辑
• 数据验证和错误处理
• 自定义编辑器和验证规则

排序

📄 阅读： references/sorting.md

• 单列和多列排序
• 自定义排序比较器
• 排序顺序和键盘导航

筛选

📄 阅读： references/filtering.md

• 筛选栏和菜单模式
• 类似 Excel 的筛选
• 自定义筛选器和谓词

搜索

📄 阅读： references/searching.md

• 全局搜索和列级搜索
• 区分大小写的搜索
• 文本高亮

选择

📄 阅读： references/selection.md

• 行、单元格和复选框选择模式
• 选择事件和 API
• 以编程方式进行选择

分页

📄 阅读： references/paging.md

• 分页配置
• 服务端分页
• 页面导航 API

滚动

📄 阅读： references/scrolling.md

• 面向大型数据集的虚拟滚动
• 无限滚动和延迟加载
• 高度/宽度管理和滚动定位

冻结列

📄 阅读： references/frozen-columns.md

• 冻结行和列
• 固定可见性配置
• 性能优化

聚合

📄 阅读： references/aggregates.md

• 汇总计算（Sum、Avg、Min、Max、Count）
• 页脚模板和子级聚合
• 聚合事件

导出与打印

📄 阅读： references/print.md

• 打印功能和模式
• 页面设置和列可见性
• 自定义打印模板

📄 阅读： references/pdf-export.md

• 带样式的 PDF 导出
• 页眉、页脚和水印
• 服务端导出

📄 阅读： references/excel-export.md

• Excel 导出配置
• 单元格样式和格式设置
• 合并单元格和自定义数据

📄 阅读： references/csv-export.md

• CSV 导出配置
• 导出时的自定义数据格式设置
• 动态文件命名
• 导出事件和回调
• 导出选中的记录

用户界面与交互

📄 阅读： references/toolbar.md

• 内置工具栏项
• 自定义工具栏项和对齐方式
• 工具栏事件处理

📄 阅读： references/clipboard.md

• 复制/粘贴操作
• 自定义剪贴板格式
• 剪贴板事件处理

📄 阅读： references/context-menu.md

• 上下文菜单配置
• 内置和自定义菜单项
• 菜单事件处理

外观与响应式设计

📄 阅读： references/adaptive.md

• 响应式与自适应设计
• 移动设备优化
• 断点与设备检测

📄 阅读： references/styling.md

• 内置主题（Material、Bootstrap、Fabric、Tailwind）
• CSS 自定义与覆盖
• 行／单元格条件样式

性能

📄 阅读： references/performance-optimization.md

• 虚拟滚动与延迟加载
• 大型数据集的分页
• 列虚拟化与渲染优化
• 查询优化策略

状态管理

📄 阅读： references/state-persistence.md

• 保存和恢复网格状态
• LocalStorage 集成
• 自定义状态管理

外键

📄 阅读： references/foreign-keys.md

• 外键列配置
• 外键值的显示文本映射
• 外键字段的下拉编辑器
• 级联外键关系
• 外键数据的远程数据绑定

行拖放

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

• 分层拖放操作
• 父子关系更新
• 防止循环层级
• 放置事件验证与约束
• 拖动操作期间的视觉反馈

验证

📄 阅读： references/validation.md

• 内置和自定义验证规则
• 对照服务端进行异步验证
• 跨字段验证模式
• 服务端验证策略
• 错误显示与突出显示
• 条件验证规则

全球化

📄 阅读： references/globalization.md

• 本地化与语言支持
• RTL（从右到左）支持
• 区域格式以及日期／数字格式

加载动画

📄 阅读： references/loading-animation.md

• 加载旋转指示器配置
• 自定义加载模板
• 加载动画自定义

无障碍与合规性

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 AA 级标准
• ARIA 标签与属性
• 键盘导航与屏幕阅读器支持
• 焦点管理与视觉指示器
• 无障碍测试指南

快速入门示例

import { Component, ViewChild } from '@angular/core';
import { TreeGridComponent } from '@syncfusion/ej2-angular-treegrid';
import { PageService, SortService, FilterService, EditService } from '@syncfusion/ej2-angular-treegrid';

@Component({
  selector: 'app-treegrid',
  template: `
    <ejs-treegrid 
      #treegrid
      [dataSource]='data'
      [childMapping]='childMapping'
      [allowPaging]='true'
      [allowSorting]='true'
      [allowFiltering]='true'
      <e-columns>
        <e-column field='TaskID' headerText='Task ID' width='90' isPrimaryKey='true'></e-column>
        <e-column field='TaskName' headerText='Task Name' width='200'></e-column>
      </e-columns>
    </ejs-treegrid>
  `,
  providers: [PageService, SortService, FilterService, EditService]
})
export class AppComponent {
  @ViewChild('treegrid') treegrid!: TreeGridComponent;

  public data: Object[] = [
    {
      TaskID: 1,
      TaskName: 'Planning',
      subtasks: [
        { TaskID: 2, TaskName: 'Scope', Duration: 4, Progress: 100 },
        { TaskID: 3, TaskName: 'Budget', Duration: 4, Progress: 100 }
      ]
    }
  ];
  
  public childMapping: string = 'subtasks';
  
  public editSettings = { mode: 'Cell', allowEditing: true, allowDeleting: true, allowAdding: true };
}

最佳实践

1. 性能优化

   • 对大型数据集（10,000 条以上记录）使用虚拟滚动
   • 实施服务端操作（排序、筛选、分页）
   • 谨慎使用冻结列，避免布局偏移

2. 数据管理

   • 始终提供主键（isPrimaryKey='true'）
   • 对分层数据使用 ChildMapping
   • 为 API 调用实施适当的错误处理

3. 用户体验

   • 获取数据期间提供加载指示器
   • 实施搜索和筛选以便查找数据
   • 编辑出错时显示验证消息
   • 支持键盘导航和无障碍功能

4. 自定义

   • 使用主题保持样式一致
   • 为常见模式创建可复用的单元格模板
   • 为条件行设置样式，提供操作指引
   • 为移动设备实施响应式设计

5. 状态管理

   • 启用状态持久化以保存用户偏好设置
   • 保存排序、筛选和列设置

关键属性概览

属性	类型	默认值	使用场景
dataSource	DataManager|Object[]	null	设置网格数据源
childMapping	string	null	子记录的属性（必须显式设置）
allowPaging	boolean	false	启用分页
allowSorting	boolean	false	启用排序
allowFiltering	boolean	false	启用筛选
editSettings	EditSettings	{}	配置编辑模式
enableVirtualization	boolean	false	启用虚拟滚动

模块注入

必须注入所需服务：

import { PageService, SortService, FilterService, EditService, ExcelExportService, PdfExportService,
  PrintService, AggregateService, ToolbarService } from '@syncfusion/ej2-angular-treegrid';

@Component({
  providers: [
    PageService, 
    SortService, 
    FilterService, 
    EditService,
    ExcelExportService,
    PdfExportService,
    PrintService,
    AggregateService,
    ToolbarService
  ]
})