syncfusion-javascript-grid

Syncfusion JavaScript Grid 组件技能

⚠️ 安全与信任边界

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

目录

• 何时使用此技能
• Grid 概述
• 内置 API 的强制规则
• 文档与导航指南
• 快速入门示例
• 常见模式
• 关键属性与配置

何时使用此技能

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

• 构建具有多个列和行的交互式数据网格
• 执行 CRUD 操作（创建、读取、更新、删除）
• 筛选、排序和搜索大型数据集
• 对数据进行分组和汇总，并显示摘要
• 将数据导出为 Excel 或 PDF 格式
• 实现行选择或多选场景
• 使用虚拟滚动创建响应式数据表
• 自定义网格样式和外观
• 处理编辑模式（行内、对话框、批量）
• 跨会话保留网格状态
• 使用 TypeScript 和现代模块系统

Grid 概述

Syncfusion EJ2 Grid 是一款功能强大、高性能的 TypeScript 数据网格组件，提供：

• 灵活的数据绑定（本地、远程、OData）
• 丰富的列功能（模板、跨列、外键、冻结）
• 高级编辑功能（行内、对话框、批量、命令列）
• 强大的筛选功能（菜单、筛选栏、类似 Excel 的筛选）
• 支持自定义聚合的多级分组
• 6 种以上的选择模式（行、单元格、列、复选框）
• 导出功能（支持模板的 Excel、PDF）
• 性能优化（虚拟滚动／无限滚动）
• 全面的自定义功能（主题、样式、事件）

内置 API 的强制规则

重要：使用 Grid 的内置 API（137 种以上的方法、65 种以上的事件、95 种以上的属性）时，请遵循以下规则：

规则 1：功能方法必须注入模块

只有注入相应模块后，方法才能生效。缺少模块时不会抛出错误。

方法	所需模块	示例
goToPage()	Page	Grid.Inject(Page) 或 Inject(Page)
sortColumn()	Sort	Grid.Inject(Sort) 或 Inject(Sort)
filterByColumn()	Filter	Grid.Inject(Filter) 或 Inject(Filter)
addRecord(), deleteRecord()	Edit	Grid.Inject(Edit) 或 Inject(Edit)

---

📄 完整属性 API 参考： references/api-reference.md 📄 完整方法 API 参考： references/programmatic-api.md 📄 完整事件 API 参考： references/events-catalog.md 📄 后端集成： references/adaptors.md

---

文档与导航指南

入门指南

📄 阅读： references/getting-started.md

• 安装和 npm 包设置
• TypeScript 模块导入与配置
• CSS 导入和主题选择
• 使用示例数据初始化基础网格
• 注入所需模块

列功能

📄 阅读： references/columns.md

• 列类型（字符串、数字、日期、布尔值）
• 列绑定与属性
• 数据类型格式化
• 列宽和基础配置
• 外键列
• 冻结列
• 列模板和自定义渲染
• 跨列
• 列宽管理
• 列选择器（显示／隐藏列）
• 列标题与自定义
• 列菜单
• 列重新排序
• 列宽调整

📄 阅读： references/command-column.md

• 命令列基础知识
• 内置命令类型（编辑、删除、保存、取消）
• 自定义命令按钮
• 命令模板
• 命令事件处理
• 行级操作

数据绑定

📄 阅读： references/data-binding.md

• 使用数组进行本地数据绑定
• 远程数据绑定（URL、OData、WebAPI）
• 查询和 URL 适配器
• 动态更改数据源
• 不可变模式，可优化大型数据集的渲染性能
• 加载指示器（Spinner、Shimmer）
• 刷新数据和切换数据源

编辑

📄 阅读： references/editing.md

• 所有 CRUD 操作的配置
• 编辑设置和模式
• 验证和错误处理
• 服务端数据持久化
• 编辑事件处理

数据验证

📄 阅读： references/validation.md

• 内置验证器（required、min、max、pattern）
• 按列数据类型（number、string、date）设置验证规则
• 自定义验证函数
• 依赖验证（根据其他列的值进行验证）
• 动态规则（在运行时添加/移除）
• 错误定位和显示
• CRUD 错误处理（客户端 + 服务端验证）
• 检测唯一字段重复值
• 使用服务端检查进行异步验证
• 与编辑模式、事件和筛选集成

筛选操作

📄 阅读： references/filter-setup.md

• 设置筛选模块
• 启用筛选功能
• 筛选类型概览
• 禁用列筛选
• 快速参考

📄 阅读： references/filter-operators.md

• 筛选运算符（21 种以上）
• 初始筛选（OR 和 AND 逻辑）
• 通配符和 LIKE 筛选
• 区分大小写
• 变音符号筛选

📄 阅读： references/filter-types.md

• 带模板生命周期的 FilterBar 筛选
• 带自定义运算符的菜单筛选
• 带多选功能的 Excel/CheckBox 筛选
• 自定义筛选 UI 组件
• 大型数据的无限滚动
• 筛选类型对比

排序

📄 阅读： references/sorting.md

• 启用列排序
• 对多列进行排序
• 自定义排序比较
• 排序方向（升序/降序）
• 使用字段映射进行排序

分组和汇总

📄 阅读： references/grouping.md

• 启用分组功能
• 按单列/多列分组
• 分组标题模板
• 多级分组
• 使用延迟加载分组提升性能
• 折叠/展开分组

📄 阅读： references/aggregates.md

• 内置汇总（Sum、Avg、Min、Max、Count）
• 自定义汇总函数
• 页脚汇总
• 分组级汇总
• 响应式汇总更新

选择模式

📄 阅读： references/selection.md

• 行选择模式
• 单元格选择模式
• 列选择模式
• 复选框选择
• 多选配置
• 选择事件和方法

行操作

📄 阅读： references/row.md

• 详细信息行模板（主从视图）
• 行拖放
• 行固定（冻结顶部/底部行）
• 行跨列
• 自定义行模板
• 行高管理

冻结和固定

📄 阅读： references/frozen.md

• 冻结列
• 冻结行
• 冻结标题
• 行固定
• 冻结列行为
• 使用冻结列优化性能
• 将冻结列与虚拟滚动结合

层级结构和嵌套数据

📄 阅读： references/hierarchy-grid.md

• 父子数据结构
• 使用 queryString 配置子网格
• 展开和折叠行为
• 嵌套网格模板
• 详细信息行模板
• 层级数据配置
• 多级层级结构（3-4 级）
• 子网格的动态数据绑定
• 以编程方式控制展开/折叠
• 嵌套数据的性能注意事项

滚动和性能

📄 阅读： references/scrolling.md

• 大型数据集的虚拟滚动
• 无限滚动
• 滚动性能优化
• 滚动事件
• 滚动行为设置

分页

📄 阅读： references/paging.md

• 页面大小配置
• 分页类型（数字、组合、自定义）
• 页面大小选项
• 当前页导航
• 总记录数处理

搜索

📄 阅读： references/searching.md

• 启用搜索功能
• 多列搜索
• 搜索运算符
• 清除搜索的方法
• 搜索性能

工具栏

📄 阅读： references/toolbar.md

• 内置工具栏项（添加、编辑、删除、保存、取消）
• 自定义工具栏模板
• 工具栏项配置
• 自定义按钮和函数
• 工具栏事件

上下文菜单

📄 阅读： references/context-menu.md

• 内置上下文菜单项
• 自定义上下文菜单
• 上下文菜单配置
• 上下文菜单事件
• 右键菜单处理
• 子菜单项和分组
• 基于选择的菜单显示

事件通信

📄 阅读： references/events-catalog.md

• 事件处理的强制规则
• 事件绑定模式（配置、addEventListener、属性赋值）
• 按类别列出的 85+ 个网格事件（生命周期、操作、行、单元格、编辑、列等）
• 操作事件的 requestType 目录
• actionBegin 和 before-events 的取消模式
• 事件时序和触发顺序
• 数据更改、用户交互和操作相关事件

导出功能

📄 阅读： references/excel-export.md

• 导出到 Excel 的基础知识
• 导出选项和自定义
• 导出时的模板渲染
• 服务端导出
• 导出筛选或分组后的数据

📄 阅读： references/pdf-export.md

• 导出到 PDF 的基础知识
• 导出选项和自定义
• 页眉和页脚
• 导出时的模板渲染
• 服务端 PDF 导出
• 页面方向和尺寸

📄 阅读： references/print.md

• 网格打印功能
• 打印设置和选项
• 打印模板
• 打印格式
• 打印预览

配置管理

📄 阅读： references/global-local.md

• 全局网格设置
• 本地列配置
• 配置优先级
• 配置合并
• 动态配置模式
• 最佳实践和模板

📄 阅读： references/state-management.md

• 将网格状态保存到存储中
• 恢复网格状态
• 跨会话保留状态
• 状态方法（保存、恢复、清除）
• 本地存储集成

⚠️ 规则：在网格中使用状态管理时，必须启用 enablePersistence: true。

本地化与国际化

📄 阅读： references/localization.md

• 多语言支持（60+ 种语言）
• 区域设置和文化配置
• 数字、日期和货币格式
• RTL 支持（阿拉伯语、希伯来语、波斯语）
• 自定义本地化和翻译
• 语言切换器实现

样式与外观

📄 阅读： references/styling-appearance.md

• 可用主题（Fluent、Bootstrap、Tailwind）
• CSS 自定义
• 自定义 CSS 类
• 行/单元格样式
• 外观方法
• 暗色模式支持

单元格

📄 阅读： references/cell.md

• 单元格选择和操作
• 获取/设置单元格值
• 单元格格式和样式
• 单元格模板
• 单元格事件和交互
• 批量单元格操作

剪贴板

📄 阅读： references/clipboard.md

• 复制/粘贴功能
• 剪贴板操作
• 复制所选单元格
• 粘贴数据
• 剪贴板格式

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• 键盘导航（Tab、Enter、Escape、方向键）
• WAI-ARIA 1.2 实现
• 屏幕阅读器支持（NVDA、JAWS）
• 颜色对比度（4.5:1、3:1）
• 焦点管理与恢复
• 用于动态更新的 ARIA live 区域
• 使用 axe 和屏幕阅读器进行无障碍测试

响应式设计

📄 阅读： references/responsive-adaptive.md

• 响应式网格布局
• 移动设备和平板电脑设计
• 触控交互与手势
• 响应式列（显示/隐藏）
• 移动设备堆叠模式
• 针对不同屏幕尺寸的媒体查询
• 处理方向变化

性能优化

📄 阅读： references/performance-optimization.md

• 大型数据集的虚拟滚动
• 延迟加载分组和详情
• 数据聚合与缓存
• 内存管理
• 性能基准测试
• 10k+ 行数据的最佳实践
• 远程数据优化

模块系统

📄 阅读： references/modules.md

• 模块注入模式
• 可用模块与功能映射
• 模块依赖项
• 包优化策略
• 常见功能组合
• 动态模块加载

数据适配器

📄 阅读： references/adaptors.md

• 用于 RESTful API 的 URL/HTTP 适配器
• 用于标准 OData 服务的 ODataV4 适配器
• 用于 ASP.NET WebAPI 的 WebAPI 适配器
• 用于旧版 ASMX Web Services 的 WebMethod 适配器
• 用于分离读写端点的 RemoteSave 适配器
• 用于专有 API 的自定义适配器
• 用于 GraphQL 端点的 GraphQL 适配器
• 适配器选择指南与比较
• 实现模式与错误处理

图表集成

📄 阅读： references/chart-integration.md

• 在详情模板中嵌入图表
• 多图表仪表板
• 网格与图表数据同步
• 交互式下钻图表
• 实时更新图表
• KPI 可视化

API 参考

📄 阅读： references/api-reference.md

• 网格属性参考
• 方法与函数签名
• 事件参考
• 设置对象（PageSettings、FilterSettings 等）
• 常见配置模式
• 快速代码示例

编程控制（方法）

📄 阅读： references/programmatic-api.md

• 网格实例参考与方法访问
• 方法的强制使用规则
• 数据和模块方法（refresh、dataBind、destroy）
• 行访问与操作方法（add、update、delete）
• 行选择方法（selectRow、selectRows、getSelectedRecords）
• 列访问与操作方法（show、hide、reorder）
• 排序、分组、筛选方法
• 编辑与批量操作方法
• 导出和打印方法（Excel、PDF、CSV）
• 工具栏与层级方法
• DOM 元素访问方法
• 实用方法（事件监听器、模板、加载指示器）
• 常见场景的快速用法示例

---

快速入门示例

import { Grid } from '@syncfusion/ej2-grids';

// Sample data
const data = [
  { OrderID: 10248, CustomerName: 'VINET', TotalAmount: 32.38 },
  { OrderID: 10249, CustomerName: 'TOMSP', TotalAmount: 11.61 }
];

// Create grid
const grid = new Grid({
  dataSource: data,
  columns: [
    { field: 'OrderID', headerText: 'Order ID', width: 120, type: 'number' },
    { field: 'CustomerName', headerText: 'Customer Name', width: 150 },
    { field: 'TotalAmount', headerText: 'Total Amount', width: 120, type: 'number', format: 'C2' }
  ],
  allowPaging: true,
  pageSettings: { pageSize: 10 },
  allowSorting: true,
  allowFiltering: true,
  selectionSettings: { type: 'Multiple', mode: 'Row' }
});

// Render grid
grid.appendTo('#grid');

---

常见模式

模式 1：带搜索的只读网格

适用于显示无需编辑的数据。启用排序、筛选和搜索。 阅读： references/getting-started.md → references/sorting.md → references/filter-setup.md → references/searching.md

模式 2：带验证的可编辑网格

适用于用户需要修改数据的情况。设置编辑模式、验证和工具栏。 阅读： references/editing.md → references/validation.md → references/toolbar.md

模式 3：分组数据与汇总

适用于按组分析聚合数据。设置分组和自定义聚合。 阅读： references/grouping.md → references/aggregates.md

模式 4：通过虚拟滚动处理大型数据集

适用于处理 1 万行以上数据时提升性能。启用虚拟滚动。 阅读： references/scrolling.md → references/paging.md

模式 5：主从层级结构

适用于显示嵌套或相关数据。设置详细信息模板。 阅读： references/row.md

模式 6：数据导出

适用于用户需要导出为 Excel 或 PDF 的场景。 阅读： references/excel-export.md → references/pdf-export.md

---

关键属性和配置

属性	类型	使用场景
dataSource	Array/URL	从本地数组或远程 URL 绑定表格数据
columns	ColumnModel[]	定义列结构、类型和模板
allowEditing	Boolean	启用行内或对话框行编辑
allowFiltering	Boolean	启用列筛选栏
allowSorting	Boolean	启用列标题排序
allowGrouping	Boolean	启用按列分组
allowPaging	Boolean	启用分页
allowSelection	Boolean	启用行或单元格选择
editSettings	EditSettings	配置编辑模式（行内/对话框/批量）
filterSettings	FilterSettings	配置筛选类型（菜单/栏/Excel）
groupSettings	GroupSettings	配置分组行为
pageSettings	PageSettings	配置页面大小和类型
selectionSettings	SelectionSettings	配置选择模式（行/单元格/复选框）
toolbar	string[]	添加用于 CRUD 操作的工具栏

---