syncfusion-react-treegrid
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSyncfusion React TreeGrid
Syncfusion React TreeGrid
A comprehensive skill for implementing and customizing Syncfusion's React TreeGrid component. TreeGrid visualizes self-referential hierarchical data in a tabular layout with expand/collapse functionality, enterprise features like virtual scrolling, and comprehensive export options.
这是一份关于实现和自定义Syncfusion React TreeGrid组件的完整指南。TreeGrid以表格布局展示自引用层级数据,具备展开/折叠功能、虚拟滚动等企业级特性,以及全面的导出选项。
When to Use This Skill
何时使用该技能
Use this skill when you need to:
- Display hierarchical or tree-structured data (organizational charts, file systems, bill of materials)
- Configure columns with proper data binding and formatting
- Implement data editing (cell, row, dialog, batch, template modes)
- Add sorting, filtering, and searching capabilities
- Handle row and cell operations (selection, templates, spanning)
- Optimize performance with virtual scrolling or infinite scrolling
- Configure paging and scrolling strategies
- Export data to PDF, Excel, or CSV formats
- Implement state persistence and aggregation
- Customize appearance with themes and styling
- Support accessibility and internationalization (RTL, localization)
在以下场景中使用本技能:
- 展示层级或树形结构数据(组织结构图、文件系统、物料清单)
- 配置具备正确数据绑定和格式化的列
- 实现数据编辑(单元格、行、对话框、批量、模板模式)
- 添加排序、筛选和搜索功能
- 处理行和单元格操作(选择、模板、合并)
- 通过虚拟滚动或无限滚动优化性能
- 配置分页和滚动策略
- 将数据导出为PDF、Excel或CSV格式
- 实现状态持久化和聚合功能
- 通过主题和样式自定义外观
- 支持无障碍访问和国际化(RTL、本地化)
TreeGrid Overview
TreeGrid概述
The TreeGrid is optimized for displaying self-referential hierarchical data with:
- Auto-expand/collapse functionality for collapsible rows
- Enterprise features: virtual scrolling, aggregates, state persistence
- Adaptive UI for mobile and small screens
- Comprehensive export: PDF, Excel, CSV formats
- Full accessibility: WCAG compliance, keyboard navigation, ARIA support
- Internationalization: RTL support, locale customization
TreeGrid针对自引用层级数据展示进行了优化,具备:
- 自动展开/折叠功能,支持可折叠行
- 企业级特性:虚拟滚动、聚合、状态持久化
- 自适应UI,适配移动端和小屏幕
- 全面导出:支持PDF、Excel、CSV格式
- 完整无障碍支持:符合WCAG标准、键盘导航、ARIA支持
- 国际化:RTL支持、区域设置自定义
Data Structure Rules
数据结构规则
Rule 1: childMapping is MANDATORY for Hierarchical Data
规则1:childMapping是层级数据的必填项
Severity: 🔴 CRITICAL - Grid will not expand/collapse without this
Requirement:
jsx
// ✅ 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>Data Format:
jsx
// ✅ CORRECT - childMapping matches 'subtasks' property
const data = [
{
TaskID: 1,
TaskName: 'Parent',
subtasks: [ // Must match childMapping value exactly
{ TaskID: 2, TaskName: 'Child' }
]
}
];Exception: Use + for flat parent-child structure:
idMappingparentIdMappingjsx
// Alternative: Flat structure with parent IDs
<TreeGridComponent
dataSource={flatData}
idMapping='TaskID'
parentIdMapping='ParentID'
hasChildMapping='isParent'>
</TreeGridComponent>严重程度:🔴 关键 - 无此配置,网格将无法展开/折叠
要求:
jsx
// ✅ 必填 - 必须与数据属性名称完全匹配
<TreeGridComponent
dataSource={data}
childMapping='subtasks'>
<ColumnsDirective>
{/* 列定义 */}
</ColumnsDirective>
</TreeGridComponent>
// ❌ 错误 - 无法正常工作
<TreeGridComponent
dataSource={data}>
{/* 无childMapping = 无法展开 */}
</TreeGridComponent>数据格式:
jsx
// ✅ 正确 - childMapping与'subtasks'属性匹配
const data = [
{
TaskID: 1,
TaskName: '父任务',
subtasks: [ // 必须与childMapping值完全匹配
{ TaskID: 2, TaskName: '子任务' }
]
}
];例外情况:对于扁平父子结构,使用 + :
idMappingparentIdMappingjsx
// 替代方案:带父ID的扁平结构
<TreeGridComponent
dataSource={flatData}
idMapping='TaskID'
parentIdMapping='ParentID'
hasChildMapping='isParent'>
</TreeGridComponent>Rule 2: Data Type Matching is MANDATORY
规则2:数据类型匹配是必填项
Severity: 🟠 IMPORTANT - Type mismatches cause rendering/sorting issues
Requirement:
jsx
// ✅ 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
}
];严重程度:🟠 重要 - 类型不匹配会导致渲染/排序问题
要求:
jsx
// ✅ 正确 - 类型与列定义匹配
const data = [
{
TaskID: 1, // 数字类型
TaskName: '规划', // 字符串类型
StartDate: new Date(), // 日期列使用Date对象
}
];
// 列定义必须与数据类型匹配
<ColumnsDirective>
<ColumnDirective field='TaskID' headerText='ID' type='number'></ColumnDirective>
<ColumnDirective field='TaskName' headerText='任务' type='string'></ColumnDirective>
<ColumnDirective field='StartDate' headerText='日期' type='date' format='yMd'></ColumnDirective>
</ColumnsDirective>
// ❌ 错误 - 类型不匹配
const data = [
{
TaskID: '1', // 应为数字却使用字符串
StartDate: '02/03/2024' // 应为Date对象却使用字符串
}
];Complete Props Reference
完整属性参考
📄 Property and Methods: references/programmatic-api.md
📄 Events Reference
📖 references/events-reference.md
- Complete event reference guide
- Data events (actionBegin, actionComplete, actionFailure)
- Editing events (cellEdit, cellSave, beforeEdit)
- Selection events (rowSelected, rowDeselected, cellSelected)
- Expand/collapse events
- Column events (drag, drop, resize, hide, show)
- Row events and utilities
📄 属性与方法:references/programmatic-api.md
📄 事件参考
📖 references/events-reference.md
- 完整的事件参考指南
- 数据事件(actionBegin、actionComplete、actionFailure)
- 编辑事件(cellEdit、cellSave、beforeEdit)
- 选择事件(rowSelected、rowDeselected、cellSelected)
- 展开/折叠事件
- 列事件(拖拽、调整大小、隐藏、显示)
- 行事件及工具方法
Documentation & Navigation Guide
文档与导航指南
Data Binding
数据绑定
📖 references/data-binding.md
- Local vs. remote data sources
- Self-referential parent-child relationships
- DataManager integration
- ExpandStateMapping for initial expand state
- Complex data binding for nested objects
📖 references/data-binding.md
- 本地与远程数据源
- 自引用父子关系
- DataManager集成
- 用于初始展开状态的ExpandStateMapping
- 嵌套对象的复杂数据绑定
Column Configuration
列配置
📖 references/column.md
- Column definitions and field mapping
- Tree column index setup
- Data types and formatting
- Column templates and custom rendering
- Headers and styling
- Foreign key columns
📖 references/column.md
- 列定义与字段映射
- 树形列索引设置
- 数据类型与格式化
- 列模板与自定义渲染
- 表头与样式
- 外键列
Row Operations
行操作
📖 references/row.md
- Row templates and custom rendering
- Row height configuration
- Row spanning
- Detail templates for nested content
- Row drag-and-drop
- Indent and outdent operations
📖 references/row.md
- 行模板与自定义渲染
- 行高配置
- 行合并
- 用于嵌套内容的详情模板
- 行拖拽
- 缩进与缩进取消操作
Cell Operations
单元格操作
📖 references/cell.md
- Cell editing
- Cell templates, styling and attributes
- Cell selection
- Cell formatting
📖 references/cell.md
- 单元格编辑
- 单元格模板、样式与属性
- 单元格选择
- 单元格格式化
Editing
编辑
📖 references/editing.md
- Cell editing mode
- Row editing mode
- Dialog editing
- Batch editing
- Template editing
- Validation rules and custom validators
- Command column editing
- Server-side persistence
📖 references/editing.md
- 单元格编辑模式
- 行编辑模式
- 对话框编辑
- 批量编辑
- 模板编辑
- 验证规则与自定义验证器
- 命令列编辑
- 服务端持久化
Sorting
排序
📖 references/sorting.md
- Single and multi-column sorting
- Initial sort order configuration
- Custom sort comparers
- Sorting with templates
- Programmatic sorting
📖 references/sorting.md
- 单列与多列排序
- 初始排序顺序配置
- 自定义排序比较器
- 结合模板的排序
- 程序化排序
Filtering
筛选
📖 references/filtering.md
- Filter bar mode
- Filter menu mode
- Excel-like filtering
- Custom filters
- Programmatic filtering
- Filter templates
📖 references/filtering.md
- 筛选栏模式
- 筛选菜单模式
- 类Excel筛选
- 自定义筛选器
- 程序化筛选
- 筛选模板
Searching
搜索
📖 references/searching.md
- Global search across all columns
- Search highlight
- Programmatic search
- Search with templates
📖 references/searching.md
- 全列全局搜索
- 搜索高亮
- 程序化搜索
- 结合模板的搜索
Selection
选择
📖 references/selection.md
- Row selection (single and multiple)
- Cell selection
- Checkbox selection
- Selection mode configuration
- Programmatic selection
- Selection change events
📖 references/selection.md
- 行选择(单选与多选)
- 单元格选择
- 复选框选择
- 选择模式配置
- 程序化选择
- 选择变更事件
Display & Layout (Performance & Presentation)
显示与布局(性能与展示)
📄 Paging
📖 references/paging.md
- Pager configuration and options
- Page size settings
- Initial page settings
- Pager template customization
- Programmatic pagination
📄 Scrolling
📖 references/scrolling.md
- Vertical and horizontal scrolling
- Scroll height configuration
- Scroll position control
- Sticky headers
- Responsive scrolling
📄 Frozen Rows and Columns
📖 references/frozen-rows-columns.md
- Freeze header rows
- Freeze columns
- Freeze direction
- Lock columns
- IsFrozen property usage
📄 Virtual Scrolling & Infinite Scrolling
📖 references/virtual-scrolling-infinite-scrolling.md
- Virtual scrolling for large datasets
- Infinite scrolling configuration
- Row height for virtual scroll
- ViewportIndex and ViewportStartIndex
- Performance optimization with virtual scroll
📄 分页
📖 references/paging.md
- 分页器配置与选项
- 页大小设置
- 初始页面设置
- 分页器模板自定义
- 程序化分页
📄 滚动
📖 references/scrolling.md
- 垂直与水平滚动
- 滚动高度配置
- 滚动位置控制
- 固定表头
- 响应式滚动
📄 冻结行与列
📖 references/frozen-rows-columns.md
- 冻结表头行
- 冻结列
- 冻结方向
- 锁定列
- IsFrozen属性用法
📄 虚拟滚动与无限滚动
📖 references/virtual-scrolling-infinite-scrolling.md
- 针对大数据集的虚拟滚动
- 无限滚动配置
- 虚拟滚动的行高设置
- ViewportIndex与ViewportStartIndex
- 结合虚拟滚动的性能优化
Aggregates
聚合
📖 references/aggregates.md
- Standard aggregates (Sum, Average, Min, Max, Count)
- Custom aggregates
- Footer aggregates
- Group aggregates
- Hierarchical aggregates for child data
📖 references/aggregates.md
- 标准聚合(求和、平均值、最小值、最大值、计数)
- 自定义聚合
- 页脚聚合
- 分组聚合
- 子数据的层级聚合
State Persistence
状态持久化
📖 references/state-persistence.md
- Global state persistence
- Local state persistence
- ExpandState tracking
- Persist sort, filter, and paging
- State restoration on reload
📖 references/state-persistence.md
- 全局状态持久化
- 本地状态持久化
- 展开状态跟踪
- 持久化排序、筛选与分页状态
- 重载时恢复状态
Toolbar
工具栏
📖 references/toolbar.md
- Built-in toolbar items
- Custom toolbar items
- Toolbar item types (Button, Separator, Dropdown)
- Toolbar item click handling
- Toolbar template customization
📖 references/toolbar.md
- 内置工具栏项
- 自定义工具栏项
- 工具栏项类型(按钮、分隔符、下拉菜单)
- 工具栏项点击处理
- 工具栏模板自定义
Context Menu
上下文菜单
📖 references/context-menu.md
- Built-in context menu items
- Custom context menu items
- Menu item click handling
- Copy/Edit/Delete operations
- Header context menu
📖 references/context-menu.md
- 内置上下文菜单项
- 自定义上下文菜单项
- 菜单项点击处理
- 复制/编辑/删除操作
- 表头上下文菜单
Adaptive View
自适应视图
📖 references/adaptive-view.md
- Adaptive UI for small screens
- Full-screen dialogs
- Horizontal row rendering
- Responsive column adjustments
- Mobile optimization
📖 references/adaptive-view.md
- 适配小屏幕的自适应UI
- 全屏对话框
- 水平行渲染
- 响应式列调整
- 移动端优化
Loading Animation
加载动画
📖 references/loading-animation.md
- Loading indicator display
- Custom loading spinner
- Loading state management
- Spinner animation control
📖 references/loading-animation.md
- 加载指示器显示
- 自定义加载 spinner
- 加载状态管理
- Spinner动画控制
Export & Print
导出与打印
📄 PDF Export
📖 references/pdf-export.md
- PDF export configuration
- Export options (columns, format)
- Headers and footers
- Page orientation and size
- Server-side export
- Exporting hierarchical data
📄 Excel Export
📖 references/excel-export.md
- Excel export configuration
- Export options (columns, formatting)
- Cell styling in export
- Headers and footers
- Server-side export
- Exporting hierarchical levels
📄 Print
📖 references/print.md
- Print configuration
- Print with custom layout
- Print specific ranges
- Print hierarchy levels
- Print preview
📄 PDF导出
📖 references/pdf-export.md
- PDF导出配置
- 导出选项(列、格式)
- 页眉与页脚
- 页面方向与尺寸
- 服务端导出
- 层级数据导出
📄 Excel导出
📖 references/excel-export.md
- Excel导出配置
- 导出选项(列、格式化)
- 导出时的单元格样式
- 页眉与页脚
- 服务端导出
- 层级数据导出
📄 打印
📖 references/print.md
- 打印配置
- 自定义布局打印
- 指定范围打印
- 层级打印
- 打印预览
Clipboard
剪贴板
📖 references/clipboard.md
- Copy cell content to clipboard
- Copy entire rows
- Paste operations
- Copy hierarchy with levels
- Clipboard event handling
📖 references/clipboard.md
- 将单元格内容复制到剪贴板
- 复制整行
- 粘贴操作
- 复制带层级的数据
- 剪贴板事件处理
Column Features (Advanced)
列高级特性
📄 Column Reorder
📖 references/column-reorder.md
- Enable column drag-and-drop reordering
- Prevent specific columns from reordering
- Reorder events and callbacks
- Programmatic column reordering
- Save/restore column order
📄 Column Resize
📖 references/column-resize.md
- Enable column drag resize
- Auto-fit columns to content
- Column width constraints (min/max)
- Resize events
- Programmatic width changes
- Save/restore column widths
📄 Column Menu
📖 references/column-menu.md
- Built-in column menu items
- Sort, filter, and column chooser from menu
- Custom menu items
- Menu events and handlers
- Conditional menu items
📄 Column Chooser
📖 references/column-chooser.md
- Toggle column visibility
- Column chooser dialog configuration
- Show/hide columns programmatically
- Column visibility events
- Save/restore column visibility
📄 Command Column
📖 references/command-column.md
- Built-in command buttons (Edit, Delete, Save, Cancel)
- Custom command buttons
- Command click handlers
- Icon customization
- Row action patterns
📄 列重排
📖 references/column-reorder.md
- 启用列拖拽重排
- 禁止特定列重排
- 重排事件与回调
- 程序化列重排
- 保存/恢复列顺序
📄 列调整大小
📖 references/column-resize.md
- 启用列拖拽调整大小
- 根据内容自动适配列宽
- 列宽约束(最小/最大值)
- 调整大小事件
- 程序化修改列宽
- 保存/恢复列宽
📄 列菜单
📖 references/column-menu.md
- 内置列菜单项
- 从菜单进行排序、筛选和列选择
- 自定义菜单项
- 菜单事件与处理程序
- 条件菜单项
📄 列选择器
📖 references/column-chooser.md
- 切换列可见性
- 列选择器对话框配置
- 程序化显示/隐藏列
- 列可见性事件
- 保存/恢复列可见性
📄 命令列
📖 references/command-column.md
- 内置命令按钮(编辑、删除、保存、取消)
- 自定义命令按钮
- 命令点击处理程序
- 图标自定义
- 行操作模式
Server Integration
服务端集成
📖 references/server-integration.md
- Remote data binding with DataManager
- Server-side CRUD operations
- Server-side filtering and sorting
- Server-side paging
- Custom request/response handling
- Error handling strategies
- Batch operations
- API endpoint patterns
📖 references/server-integration.md
- 使用DataManager进行远程数据绑定
- 服务端CRUD操作
- 服务端筛选与排序
- 服务端分页
- 自定义请求/响应处理
- 错误处理策略
- 批量操作
- API端点模式
Validation Patterns
验证模式
📖 references/validation-patterns.md
- Column validation rules
- Custom validation logic
- Cross-field validation
- Async validation (API calls)
- Server-side validation
- Dialog form validation
- Conditional validation
- Error message display
📖 references/validation-patterns.md
- 列验证规则
- 自定义验证逻辑
- 跨字段验证
- 异步验证(API调用)
- 服务端验证
- 对话框表单验证
- 条件验证
- 错误消息显示
Performance Optimization
性能优化
📖 references/performance-optimization.md
- Virtual scrolling for large datasets (100k+ rows)
- Infinite scrolling with caching
- Bundle size optimization
- Disabling unnecessary features
- Server-side operations optimization
- Memoization and rendering optimization
- Template optimization
- Event handler optimization
- Benchmarking and performance monitoring
- Performance checklist
📖 references/performance-optimization.md
- 针对大数据集(10万+行)的虚拟滚动
- 带缓存的无限滚动
- 包体积优化
- 禁用不必要的特性
- 服务端操作优化
- 记忆化与渲染优化
- 模板优化
- 事件处理程序优化
- 基准测试与性能监控
- 性能检查清单
Customization
自定义
📖 references/styling-appearance.md
- CSS class customization
- Theme selection (Material, Bootstrap, Fluent, Tailwind)
- CSS variable overrides
- Component-specific styling
- Dark mode support
- Row styling
- Cell styling
📖 references/styling-appearance.md
- CSS类自定义
- 主题选择(Material、Bootstrap、Fluent、Tailwind)
- CSS变量覆盖
- 组件特定样式
- 深色模式支持
- 行样式
- 单元格样式
Globalization
全球化
📖 references/globalization.md
- Internationalization (i18n)
- Localization (l10n) for UI text
- Right-to-left (RTL) support
- Date formatting per locale
- Number formatting per locale
- Currency localization
📖 references/globalization.md
- 国际化(i18n)
- UI文本本地化(l10n)
- 从右到左(RTL)支持
- 按区域设置格式化日期
- 按区域设置格式化数字
- 货币本地化
Accessibility
无障碍访问
📖 references/accessibility.md
- WCAG 2.1 Level AA compliance
- Keyboard navigation (all shortcuts)
- ARIA attributes and screen reader support
- Expand/collapse keyboard shortcuts
- Editing keyboard navigation
- Selection shortcuts
📖 references/accessibility.md
- 符合WCAG 2.1 AA级标准
- 键盘导航(所有快捷键)
- ARIA属性与屏幕阅读器支持
- 展开/折叠键盘快捷键
- 编辑键盘导航
- 选择快捷键
Quick Start Example
快速开始示例
tsx
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>
);
}tsx
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: '规划',
parentID: null,
Children: [{ TaskID: 2, TaskName: '规划时间线', parentID: 1 }]
}
];
return (
<TreeGridComponent
dataSource={data}
childMapping="Children"
treeColumnIndex={1}
height="auto"
allowPaging={true}
>
<ColumnsDirective>
<ColumnDirective field="TaskID" headerText="任务ID" width={80} />
<ColumnDirective field="TaskName" headerText="任务名称" width={160} />
</ColumnsDirective>
<Inject services={[Page]} />
</TreeGridComponent>
);
}Core Configuration
核心配置
| Property | Type | Default | Description |
|---|---|---|---|
| Array | DataManager | | Data source for TreeGrid |
| string | | Property name for child records (e.g., "Children") |
| string | | Property name for unique ID (flat data) |
| string | | Property name for parent ID (flat data) |
| string | | Property for lazy load indicator |
| number | | Column index for tree expand icons |
| string | | Property for initial expand state |
| 属性 | 类型 | 默认值 | 描述 |
|---|---|---|---|
| Array | DataManager | | TreeGrid的数据源 |
| string | | 子记录的属性名称(例如"Children") |
| string | | 唯一ID的属性名称(扁平数据) |
| string | | 父ID的属性名称(扁平数据) |
| string | | 懒加载指示器的属性 |
| number | | 树形展开图标的列索引 |
| string | | 初始展开状态的属性 |