syncfusion-react-treegrid

Syncfusion React TreeGrid

用于实现和自定义 Syncfusion React TreeGrid 组件的综合技能。TreeGrid 以表格布局可视化自引用层级数据，支持展开/折叠功能、虚拟滚动等企业级功能，以及全面的导出选项。

目录

• 何时使用此技能
• TreeGrid 概述
• 数据结构规则
• 文档导航指南
• 快速入门示例

何时使用此技能

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

• 显示层级数据或树形结构数据（组织架构图、文件系统、物料清单）
• 配置具有恰当数据绑定和格式的列
• 实现数据编辑（单元格、行、对话框、批量、模板模式）
• 添加排序、筛选和搜索功能
• 处理行和单元格操作（选择、模板、跨行列）
• 使用虚拟滚动或无限滚动优化性能
• 配置分页和滚动策略
• 将数据导出为 PDF、Excel 或 CSV 格式
• 实现状态持久化和聚合
• 使用主题和样式自定义外观
• 支持无障碍访问和国际化（RTL、本地化）

TreeGrid 概述

TreeGrid 针对显示自引用层级数据进行了优化，具有以下功能：

• 自动展开/折叠：支持可折叠行
• 企业级功能：虚拟滚动、聚合、状态持久化
• 自适应 UI：适用于移动设备和小屏幕
• 全面导出：支持 PDF、Excel、CSV 格式
• 全面的无障碍访问支持：符合 WCAG 标准，支持键盘导航和 ARIA
• 国际化：支持 RTL 和区域设置自定义

数据结构规则

规则 1：层级数据必须设置 childMapping

严重性：🔴 严重 — 未设置此项时，网格无法展开/折叠

要求：

// ✅ REQUIRED - Must match data property name exactly
<TreeGridComponent 
  dataSource={data}
  childMapping='subtasks'>
  <ColumnsDirective>
    {/* Columns */}
  </ColumnsDirective>
</TreeGridComponent>

// ❌ WRONG - Will not work
<TreeGridComponent 
  dataSource={data}>
  {/* No childMapping = No expansion possible */}
</TreeGridComponent>

数据格式：

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

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

// Alternative: Flat structure with parent IDs
<TreeGridComponent 
  dataSource={flatData}
  idMapping='TaskID'
  parentIdMapping='ParentID'
  hasChildMapping='isParent'>
</TreeGridComponent>

---

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

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

要求：

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

// Column definition must match data types
<ColumnsDirective>
  <ColumnDirective field='TaskID' headerText='ID' type='number'></ColumnDirective>
  <ColumnDirective field='TaskName' headerText='Task' type='string'></ColumnDirective>
  <ColumnDirective field='StartDate' headerText='Date' type='date' format='yMd'></ColumnDirective>
</ColumnsDirective>

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

完整属性参考

📄 属性和方法： references/programmatic-api.md

📄 事件参考 📖 references/events-reference.md

• 完整的事件参考指南
• 数据事件（actionBegin、actionComplete、actionFailure）
• 编辑事件（cellEdit、cellSave、beforeEdit）
• 选择事件（rowSelected、rowDeselected、cellSelected）
• 展开/折叠事件
• 列事件（拖动、放置、调整大小、隐藏、显示）
• 行事件和实用工具

---

文档导航指南

数据绑定

📖 references/data-binding.md

• 本地与远程数据源
• 自引用父子关系
• DataManager 集成
• 用于初始展开状态的 ExpandStateMapping
• 嵌套对象的复杂数据绑定

列配置

📖 references/column.md

• 列定义和字段映射
• 树形列索引设置
• 数据类型和格式
• 列模板和自定义渲染
• 表头和样式
• 外键列

行操作

📖 references/row.md

• 行模板和自定义渲染
• 行高配置
• 行跨越
• 用于嵌套内容的详细信息模板
• 行拖放
• 缩进和取消缩进操作

单元格操作

📖 references/cell.md

• 单元格编辑
• 单元格模板、样式和属性
• 单元格选择
• 单元格格式设置

编辑

📖 references/editing.md

• 单元格编辑模式
• 行编辑模式
• 对话框编辑
• 批量编辑
• 模板编辑
• 验证规则和自定义验证器
• 命令列编辑
• 服务器端持久化

排序

📖 references/sorting.md

• 单列和多列排序
• 初始排序顺序配置
• 自定义排序比较器
• 使用模板排序
• 程序化排序

筛选

📖 references/filtering.md

• 筛选栏模式
• 筛选菜单模式
• 类 Excel 筛选
• 自定义筛选器
• 程序化筛选
• 筛选模板

搜索

📖 references/searching.md

• 跨所有列进行全局搜索
• 搜索高亮
• 程序化搜索
• 使用模板搜索

选择

📖 references/selection.md

• 行选择（单选和多选）
• 单元格选择
• 复选框选择
• 选择模式配置
• 程序化选择
• 选择变更事件

显示与布局（性能与呈现）

📄 分页 📖 references/paging.md

• 分页器配置和选项
• 每页条目数设置
• 初始页面设置
• 分页器模板自定义
• 程序化分页

📄 滚动 📖 references/scrolling.md

• 垂直和水平滚动
• 滚动高度配置
• 滚动位置控制
• 粘性表头
• 响应式滚动

📄 冻结行和列 📖 references/frozen-rows-columns.md

• 冻结表头行
• 冻结列
• 冻结方向
• 锁定列
• IsFrozen 属性用法

📄 虚拟滚动与无限滚动 📖 references/virtual-scrolling-infinite-scrolling.md

• 面向大型数据集的虚拟滚动
• 无限滚动配置
• 虚拟滚动的行高
• ViewportIndex 和 ViewportStartIndex
• 使用虚拟滚动优化性能

汇总

📖 references/aggregates.md

• 标准汇总（Sum、Average、Min、Max、Count）
• 自定义汇总
• 页脚汇总
• 分组汇总
• 子数据的分层汇总

状态持久化

📖 references/state-persistence.md

• 全局状态持久化
• 本地状态持久化
• ExpandState 跟踪
• 持久化排序、筛选和分页状态
• 重新加载时恢复状态

工具栏

📖 references/toolbar.md

• 内置工具栏项
• 自定义工具栏项
• 工具栏项类型（Button、Separator、Dropdown）
• 工具栏项点击处理
• 工具栏模板自定义

上下文菜单

📖 references/context-menu.md

• 内置上下文菜单项
• 自定义上下文菜单项
• 菜单项点击处理
• 复制／编辑／删除操作
• 表头上下文菜单

自适应视图

📖 references/adaptive-view.md

• 面向小屏幕的自适应 UI
• 全屏对话框
• 水平行呈现
• 响应式列调整
• 移动端优化

加载动画

📖 references/loading-animation.md

• 加载指示器显示
• 自定义加载旋转图标
• 加载状态管理
• 旋转图标动画控制

导出与打印

📄 PDF 导出 📖 references/pdf-export.md

• PDF 导出配置
• 导出选项（列、格式）
• 页眉和页脚
• 页面方向和尺寸
• 服务端导出
• 导出分层数据

📄 Excel 导出 📖 references/excel-export.md

• Excel 导出配置
• 导出选项（列、格式设置）
• 导出时的单元格样式
• 页眉和页脚
• 服务端导出
• 导出分层级数据

📄 打印 📖 references/print.md

• 打印配置
• 使用自定义布局打印
• 打印指定范围
• 打印层级
• 打印预览

剪贴板

📖 references/clipboard.md

• 将单元格内容复制到剪贴板
• 复制整行
• 粘贴操作
• 按层级复制层级结构
• 剪贴板事件处理

列功能（高级）

📄 列重新排序 📖 references/column-reorder.md

• 启用列拖放重新排序
• 禁止特定列重新排序
• 重新排序事件和回调
• 以编程方式重新排列列

📄 列宽调整 📖 references/column-resize.md

• 启用拖动调整列宽
• 根据内容自动调整列宽
• 列宽限制（最小值/最大值）
• 调整列宽事件
• 以编程方式更改列宽
• 保存/恢复列宽

📄 列菜单 📖 references/column-menu.md

• 内置列菜单项
• 通过菜单排序、筛选和选择列
• 自定义菜单项
• 菜单事件和处理程序
• 条件菜单项

📄 列选择器 📖 references/column-chooser.md

• 切换列的可见性
• 配置列选择器对话框
• 以编程方式显示/隐藏列
• 列可见性事件
• 保存/恢复列可见性

📄 命令列 📖 references/command-column.md

• 内置命令按钮（编辑、删除、保存、取消）
• 自定义命令按钮
• 命令点击处理程序
• 图标自定义
• 行操作模式

服务端集成

📖 references/server-integration.md

• 使用 DataManager 绑定远程数据
• 服务端 CRUD 操作
• 服务端筛选和排序
• 服务端分页
• 自定义请求/响应处理
• 错误处理策略
• 批量操作

验证模式

📖 references/validation-patterns.md

• 列验证规则
• 自定义验证逻辑
• 跨字段验证
• 异步验证（API 调用）
• 服务端验证
• 对话框表单验证
• 条件验证
• 显示错误消息

性能优化

📖 references/performance-optimization.md

• 大型数据集（100k+ 行）的虚拟滚动
• 带缓存的无限滚动
• 包体积优化
• 禁用不必要的功能
• 服务端操作优化
• 记忆化和渲染优化
• 模板优化
• 事件处理程序优化
• 基准测试和性能监控
• 性能检查清单

自定义

📖 references/styling-appearance.md

• CSS 类自定义
• 主题选择（Material、Bootstrap、Fluent、Tailwind）
• CSS 变量覆盖
• 组件专属样式
• 深色模式支持
• 行样式
• 单元格样式

全球化

📖 references/globalization.md

• 国际化（i18n）
• UI 文本本地化（l10n）
• 从右向左（RTL）支持
• 按区域设置格式化日期
• 按区域设置格式化数字
• 货币本地化

无障碍访问

📖 references/accessibility.md

• 符合 WCAG 2.1 AA 级标准
• 键盘导航（所有快捷键）
• ARIA 属性和屏幕阅读器支持
• 展开/折叠键盘快捷键
• 编辑键盘导航
• 选择快捷键

快速入门示例

import React from 'react';
import { TreeGridComponent, ColumnsDirective, ColumnDirective, Inject, Page } from '@syncfusion/ej2-react-treegrid';
import { DataManager, UrlAdaptor } from '@syncfusion/ej2-data';

interface ITreeData {
  TaskID?: number;
  TaskName?: string;
  parentID: number | null;
  Children?: ITreeData[];
}

export default function App() {
  const data: ITreeData[] = [
    {
      TaskID: 1,
      TaskName: 'Planning',
      parentID: null,
      Children: [{ TaskID: 2, TaskName: 'Plan timeline', parentID: 1 }]
    }
  ];

  return (
    <TreeGridComponent
      dataSource={data}
      childMapping="Children"
      treeColumnIndex={1}
      height="auto"
      allowPaging={true}
    >
      <ColumnsDirective>
        <ColumnDirective field="TaskID" headerText="Task ID" width={80} />
        <ColumnDirective field="TaskName" headerText="Task Name" width={160} />
      </ColumnsDirective>
      <Inject services={[Page]} />
    </TreeGridComponent>
  );
}

核心配置

属性	类型	默认值	说明
dataSource	Array | DataManager	[]	TreeGrid 的数据源
childMapping	string	null	子记录的属性名称（例如，“Children”）
idMapping	string	null	唯一 ID 的属性名称（平面数据）
parentIdMapping	string	null	父级 ID 的属性名称（平面数据）
hasChildMapping	string	null	延迟加载指示器的属性
treeColumnIndex	number	0	树展开图标所在的列索引
expandStateMapping	string	null	初始展开状态的属性