syncfusion-javascript-treegrid

Syncfusion TypeScript TreeGrid

这是一份全面的技能指南，介绍如何实现和自定义 Syncfusion 的 Javascript TreeGrid 组件。TreeGrid 可在表格布局中可视化自引用层级数据，并支持展开/折叠功能、虚拟滚动等企业级功能，以及全面的导出选项。

## ⚠️ 安全与信任边界

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

何时使用此技能

在需要以下功能时使用此技能：

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

不要将此技能用于：

• 简单的平面表格显示（请改用 DataGrid）
• 树视图组件（请改用 TreeView 控件）
• 文件上传/下载处理（属于独立事项）

目录

• TreeGrid 概述
• 数据结构规则
• API 参考
• 功能概述与导航指南
• 快速入门示例

TreeGrid 概述

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

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

数据结构规则

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

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

要求：

import { TreeGrid } from '@syncfusion/ej2-treegrid';

// ✅ REQUIRED - childMapping matches data property name exactly
let treeGridObj: TreeGrid = new TreeGrid({
    dataSource: hierarchicalData,
    childMapping: 'subtasks',  // Must match property in data
    treeColumnIndex: 0,
    columns: [
        { field: 'taskID', headerText: 'Task ID', width: 90 },
        { field: 'taskName', headerText: 'Task Name', width: 200 }
    ]
});

// ❌ WRONG - No childMapping = No expansion possible
let treeGridObj2: TreeGrid = new TreeGrid({
    dataSource: hierarchicalData,
    // Missing childMapping - Won't work!
    columns: [...]
});

数据格式：

// ✅ CORRECT - childMapping matches 'subtasks' property
const hierarchicalData = [
  {
    taskID: 1,
    taskName: 'Planning',
    subtasks: [  // Must match childMapping value exactly
      { taskID: 2, taskName: 'Identify Site' },
      { taskID: 3, taskName: 'Perform Test' }
    ]
  }
];

// Alternative: Flat structure with parent IDs
const flatData = [
    { taskID: 1, taskName: 'Planning', parentID: null, isParent: true },
    { taskID: 2, taskName: 'Identify Site', parentID: 1, isParent: false }
];

let treeGridObj3: TreeGrid = new TreeGrid({
    dataSource: flatData,
    idMapping: 'taskID',
    parentIdMapping: 'parentID',
    hasChildMapping: 'isParent'
});

规则 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
let treeGridObj: TreeGrid = new TreeGrid({
    dataSource: data,
    columns: [
        { field: 'taskID', headerText: 'ID', type: 'number', width: 90 },
        { field: 'taskName', headerText: 'Task', type: 'string', width: 200 },
        { field: 'startDate', headerText: 'Date', type: 'date', format: 'yMd', width: 120 }
    ]
});

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

---

API 参考

属性与方法

📄 阅读： references/api-properties-methods.md

• 完整的属性参考（83 个属性）
• 按类别整理：数据与配置、行为与显示、选择、编辑、导出、高级
• 所有方法（共 108 个）
• 方法签名和返回类型
• 何时使用？配置设置、CRUD 操作、DOM 操作、行/单元格管理

事件与模块

📄 阅读： references/api-events-modules.md

• 完整的事件参考（66 个事件）
• 按生命周期整理事件：生命周期事件、数据、编辑、选择、展开/折叠、导出、UI 交互、拖放
• 功能模块（共 15 个）
• 模块注入模式及其用法
• 何时使用？响应网格状态变化、处理用户交互、优化功能加载

---

功能概述与导航指南

TreeGrid 组件提供全面的功能，用于管理、显示和交互层级数据。以下是按功能领域整理的完整导航指南。

入门

📄 阅读： references/getting-started.md

• 安装和软件包配置
• TypeScript 配置
• TreeGrid 基本初始化
• 最简数据绑定示例
• 首个树结构设置

数据处理与绑定

📄 阅读： references/data-handling.md

• 本地数据绑定（层次结构和自引用结构）
• 使用 childMapping 绑定层次数据（嵌套数组）
• 使用 idMapping/parentIdMapping 绑定自引用数据（扁平数据）
• 使用 DataManager 和适配器绑定远程数据
• 按需加载子记录，实现延迟加载
• 离线模式，用于客户端处理
• 自定义适配器以扩展功能
• 使用 Fetch API 进行 AJAX 绑定
• 不可变模式，用于性能优化
• 错误处理以及通过 DataManager 执行 CRUD 操作

列配置与功能

📄 阅读： references/columns.md

• 列基础知识（字段绑定、类型、主键、按列控制操作）
• 列类型（string、number、date、datetime、boolean）和格式设置
• 标题自定义（文本、模板、自定义 HTML）
• 列模板和值访问器（自定义格式设置、计算列）
• 复杂数据绑定，支持点表示法（嵌套对象、层次数据）
• 列宽调整，支持最小/最大宽度限制
• 通过拖放或编程 API 重新排列列
• 列可见性控制（逐列显示/隐藏）
• 列菜单，支持排序、筛选和自动适应宽度操作
• 列选择器，供最终用户管理列的可见性
• 列跨列，实现单元格水平合并
• 响应式列，根据媒体查询显示/隐藏
• 自动调整列宽以适应内容
• 冻结列：使用 isFrozen 锁定特定列，使其在滚动时保持可见
• 冻结方向：在左侧或右侧冻结列（freeze: 'Left'|'Right'）
• 4 区域冻结布局：组合使用 frozenRows + frozenColumns，创建主从网格

行功能与模板

📄 阅读： references/row-features.md

• 行选择模式（单选、多选）
• 复选框选择
• 行详情/模板展开
• 行拖放
• 行缩进和跨行
• 行高配置
• 冻结行：垂直滚动时保持顶部 N 行可见（frozenRows）
• 冻结行和列：创建 4 区域布局，用于主从网格
• 冻结行与层次结构：冻结的父行仍可展开/折叠
• 冻结行与详情模板：将冻结行与主从模式结合使用

编辑操作

📄 阅读： references/editing.md

• CRUD 操作设置（创建、读取、更新、删除）
• 编辑模式（单元格、行、对话框、批量）及其使用场景
• 编辑类型和组件（文本、数字、下拉列表、日期、复选框）
• 自定义编辑模板，采用 create/write/read 模式
• 字段验证（必填、类型、自定义规则）
• 工具栏操作和删除确认对话框
• 命令列，包含内置和自定义按钮
• 默认值和禁用列编辑
• 使用 URL Adaptor 和 Remote Save Adaptor 持久化到服务器
• 服务端 CRUD 操作处理程序（插入、更新、删除、批量）

排序功能

📄 阅读： references/sorting.md

• 排序基础：点击列标题可切换升序/降序
• 初始排序：通过 sortSettings 设置加载时的默认排序列
• 多列排序：使用 CTRL+Click 按多个列排序
• 排序配置：禁用特定列的排序，设置默认方向
• 排序方法：以编程方式排序或清除排序（sortByColumn、clearSorting）
• 排序事件：响应排序开始/完成事件（actionBegin、actionComplete）
• 排序 UI：列标题图标指示排序方向
• 触控交互：在触控设备上使用多列排序弹出窗口
• 常见模式：排序与筛选的组合、层次排序行为

搜索与快速查找

📄 阅读： references/searching.md

• 搜索基础：启用工具栏搜索框，按文本筛选
• 初始搜索：在加载时设置默认搜索值和配置
• 搜索运算符：包含、以……开头、以……结尾、等于、不等于匹配
• 搜索配置：配置可搜索列和 ignoreCase 行为
• 外部搜索按钮：通过自定义 UI 以编程方式触发搜索
• 搜索特定列：仅将搜索范围限制在特定列字段
• 搜索方法：使用 search() 方法以编程方式搜索
• 常见模式：搜索 + 排序、搜索 + 筛选组合

筛选选项

📄 阅读： references/filtering.md

• 筛选基础和配置
• 筛选层级模式（Parent、Child、Both、None）
• 通过 filterSettings.columns 设置初始筛选
• 筛选运算符和表达式
• 带自定义模板的筛选栏
• 带自定义组件的筛选菜单
• 类 Excel 筛选界面
• 变音符号和特殊字符处理
• 以编程方式筛选的方法

聚合与汇总

📄 阅读： references/aggregation.md

• 聚合类型（sum、average、count、min、max、custom）
• 页脚聚合显示
• 分组级聚合
• 自定义聚合模板

Excel 导出

📄 阅读： references/excel-export.md

• 保留层级结构的基础 Excel 导出
• 导出选项：保留折叠状态、包含隐藏列、导出时显示/隐藏列
• 自定义文件名和自定义数据源
• 单元格样式：条件格式（excelQueryCellInfo 事件）、应用主题
• 带样式、超链接和对齐方式的页眉与页脚
• 服务端导出：ASP.NET MVC 配置、serverExcelExport 方法
• CSV 导出（服务端）：serverCsvExport 方法
• 使用 excelAggregateQueryCellInfo 事件导出自定义聚合

PDF 导出

📄 阅读： references/pdf-export.md

• 带层级布局的基础 PDF 导出
• 导出选项：包含隐藏列、显示/隐藏列、页面方向、页面大小
• 自定义文件名和字体（标准字体 + 自定义字体）
• 单元格样式：条件格式（pdfQueryCellInfo 事件）、应用主题
• 页眉与页脚：文本、线条、页码、可定位的图像
• 服务端导出：ASP.NET MVC 配置、serverPdfExport 方法
• 使用 BeginCellLayout 事件旋转页眉（仅限服务端）

性能优化

📄 阅读： references/performance.md

• 性能最佳实践
• 变更检测策略
• 延迟加载数据模式
• 内存管理
• 监控和优化技术

样式与外观

📄 阅读： references/styling-and-appearance.md

• 主题配置：Material、Bootstrap、Fabric、HighContrast、Tailwind
• CSS 自定义：使用自定义 CSS 类覆盖默认样式
• 自适应 UI：启用 enableAdaptiveUI，为移动设备提供带响应式对话框的友好界面
• CSS 类参考：TreeGrid CSS 类完整列表（根元素、页眉、正文、分页器、汇总）
• CSS 类自定义：使用针对性 CSS 覆盖特定区域

选择与交互

📄 阅读： references/selection-and-interaction.md

• 单元格和行的选择模式
• 复选框选择
• 鼠标和键盘交互
• 上下文菜单集成
• 剪贴板操作（复制、剪切、粘贴）
• 选择类型：单行/单元格选择与多行/单元格选择
• 选择模式：行选择、单元格选择、两种模式
• 行选择：初始选择、条件选择、以编程方式获取选中行
• 单元格选择：流式与框选模式
• 复选框选择及表头全选选项
• 以编程方式控制选择（selectRow、selectRows、getSelectedRecords）
• 切换选择：再次单击已选中的行可取消选择
• 触摸交互：在触摸设备上显示多选弹出窗口
• 选择事件和事件处理程序（rowSelected、cellSelected）
• 对选中行执行批量操作（删除、归档等）

上下文菜单

📄 阅读： references/context-menu.md

• 上下文菜单基础：通过注入 ContextMenu 模块启用
• 默认菜单项：自动调整、编辑、删除、导出、排序、分页、缩进、取消缩进
• 自定义菜单项：使用 text、target 和 id 属性定义自定义菜单项
• 自定义菜单项操作：在 contextMenuClick 事件处理程序中处理
• 动态启用/禁用：使用 contextMenuOpen 事件切换菜单项的可用状态
• 特定目标的菜单：使用 target 属性在表头、行或内容区域显示菜单
• 常见场景：展开/折叠行、编辑/删除记录、导出操作

分页配置

📄 阅读： references/paging.md

• 通过注入 Page 模块并设置 allowPaging 属性来配置分页
• 页面大小模式：All（总数）与 Root（仅父项数）
• 页面大小下拉列表：允许用户动态更改每页行数
• 使用页面导航控件自定义分页器模板
• 分页器位置：将分页器从底部移至顶部
• 以编程方式切换页面（goToPage、goToNextPage、goToPreviousPage）
• 页面更改事件（actionComplete，requestType 为 'paging'）
• 根据屏幕宽度调整页面大小
• 跟踪页面更改以加载数据或更新 UI

滚动与性能

📄 阅读： references/scrolling.md

• 基本滚动：具有固定高度/宽度的容器，并自动显示滚动条
• 响应式滚动：在父容器中设置 100% 高度/宽度
• 固定表头：使用 enableStickyHeader 滚动时保持列标题可见
• 滚动到行：跳转到特定行，或将选中行滚动到视图中
• 行虚拟化：对于包含 10,000+ 行的数据集，仅渲染可见行（enableVirtualization）
• 列虚拟化：对于包含 100+ 列的网格，仅渲染可见列（enableColumnVirtualization）
• 无限滚动：用户向下滚动时加载缓冲页面（enableInfiniteScrolling）
• 无限滚动缓存模式：缓存已加载的页面，避免重复获取
• 性能对比：何时使用分页、虚拟滚动或无限滚动
• 虚拟滚动与无限滚动：虚拟滚动适用于客户端数据，无限滚动适用于服务端数据
• 限制：虚拟滚动/无限滚动不支持批量编辑、详细信息模板和行模板

高级功能与操作

📄 阅读： references/advanced-features.md

• 打印：工具栏打印按钮、打印模式（全部/当前页）、打印时显示/隐藏列
• 工具栏：内置项、自定义工具栏按钮、启用/禁用工具栏项
• 剪贴板：复制/粘贴快捷键、层级模式、批量编辑中的自动填充
• 状态持久化：启用持久化、读取/设置 localStorage、持久化属性

加载动画

📄 阅读： references/loading-animation.md

• Spinner 和 Shimmer 加载指示器类型
• 数据操作期间自动显示
• 远程数据源加载

全局本地化与无障碍功能

📄 阅读： references/global-local-accessibility.md

• 本地化：使用 L10n.load() 加载特定文化的翻译，设置 locale 属性
• 依赖组件的本地化：DatePicker、Form Validator、Grid
• 国际化：使用 loadCldr、setCulture、setCurrencyCode 格式化数字和日期
• 从右到左（RTL）：为阿拉伯语、波斯语、乌尔都语启用 enableRtl 属性
• 无障碍合规：WCAG 2.2、Section 508、屏幕阅读器支持标准
• WAI-ARIA 属性：role=treegrid、aria-selected、aria-expanded、aria-sort、aria-busy、aria-label
• 键盘导航：完整的键盘快捷键和无障碍检查器验证

测试与测试辅助工具

📄 阅读： references/testing-and-helpers.md

• 辅助 API 参考：20 多个用于访问 DOM 元素和操作属性的辅助方法
• 设置 Cypress：初始化项目、安装 Syncfusion 包、配置 Cypress
• 初始化 TreeGridHelper：导入并使用元素 ID 实例化辅助工具
• 使用 setModel/getModel：动态设置和获取 TreeGrid 属性
• 使用 invoke 函数：以编程方式调用 TreeGrid 方法（collapseAll、expandAll、print、export）
• 测试元素访问：获取表头、页脚、分页器、对话框、筛选器和内容元素
• 编写测试用例：提供属性访问、方法调用和 UI 交互的完整示例
• 运行 Cypress：交互模式、无头模式、浏览器选择、指定 spec 文件
• 最佳实践：使用辅助工具代替 CSS 选择器、设置有意义的延迟、准备数据、清理

---

快速入门示例

以下是使用 vanilla Inject 模式的最简 TypeScript TreeGrid 设置：

import { TreeGrid, Page, Edit } from '@syncfusion/ej2-treegrid';

// Data interface for type safety
interface TreeGridData {
  taskID: number;
  taskName: string;
  startDate: Date;
  endDate: Date;
  duration: number;
  progress: number;
  subtasks?: TreeGridData[];
}

// Sample hierarchical data
const data: TreeGridData[] = [
  {
    taskID: 1,
    taskName: 'Planning',
    startDate: new Date('02/03/2017'),
    endDate: new Date('02/07/2017'),
    duration: 5,
    progress: 100,
    subtasks: [
      {
        taskID: 2,
        taskName: 'Identify Site location',
        startDate: new Date('02/03/2017'),
        endDate: new Date('02/04/2017'),
        duration: 2,
        progress: 100
      },
      {
        taskID: 3,
        taskName: 'Perform soil test',
        startDate: new Date('02/04/2017'),
        endDate: new Date('02/05/2017'),
        duration: 1,
        progress: 100
      }
    ]
  }
];

// Inject required modules
TreeGrid.Inject(Page, Edit);

// Initialize TreeGrid
let treeGridObj: TreeGrid = new TreeGrid({
    dataSource: data,
    childMapping: 'subtasks',
    allowPaging: true,
    pageSettings: { pageSize: 10 },
    editSettings: { allowEditing: true, allowAdding: true, allowDeleting: true, mode: 'Row' },
    treeColumnIndex: 1,
    columns: [
        { field: 'taskID', headerText: 'Task ID', isPrimaryKey: true, width: 90, textAlign: 'Right' },
        { field: 'taskName', headerText: 'Task Name', width: 180, textAlign: 'Left' },
        { field: 'startDate', headerText: 'Start Date', width: 90, textAlign: 'Right', type: 'date', format: 'yMd' },
        { field: 'duration', headerText: 'Duration', width: 80, textAlign: 'Right' },
        { field: 'progress', headerText: 'Progress (%)', width: 80, textAlign: 'Right' }
    ]
});

treeGridObj.appendTo('#TreeGrid');