syncfusion-react-grid

Syncfusion React Grid

Syncfusion React Grid 是一款功能全面、内容丰富的组件，用于显示和操作表格数据。它提供丰富的功能，包括数据绑定、分页、排序、筛选、分组、编辑、导出、滚动模式、行列自定义和高级状态管理，可高效处理任意规模和复杂程度的数据集。

⚠️ 安全与信任边界

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

目录

• 何时使用此技能
• 组件概述
• 内置 API 的强制规则
• 功能／技能导航指南
• 快速入门示例

何时使用此技能

在以下情况下使用 Syncfusion React Grid：

• 显示表格数据，在 React 应用中使用行和列
• 高效处理大型数据集，使用分页、虚拟滚动或无限滚动
• 启用排序、筛选和搜索，支持单列或多列
• 内联编辑数据，支持多种编辑模式（Inline、Batch、Dialog）
• 导出数据，可自定义为 Excel 或 PDF 格式
• 分组和汇总数据，并提供摘要和计算
• 自定义行和单元格，使用模板和样式
• 管理复杂的列配置（冻结列、跨列、重新排序、调整大小）
• 优化性能，以便渲染数千条记录
• 持久化 Grid 状态，保存用户偏好和配置
• 提供响应式数据视图，适配不同屏幕尺寸

组件概述

Grid 组件提供：

• 数据绑定：支持本地数组、远程数据源和 DataManager 集成
• 分页：客户端分页，可自定义页面大小和导航
• 排序：支持单列和多列排序，以及自定义比较器
• 筛选：支持多种筛选模式（Filter Bar、Filter Menu、类似 Excel 的筛选）
• 搜索：跨列全局搜索
• 分组：按列分组数据，支持汇总和延迟加载
• 选择：支持行、单元格和列选择，以及复选框
• 编辑：支持 Inline、Batch 和 Dialog 模式，并提供验证和模板
• 汇总：支持 Sum、Average、Count、Min、Max，并在页脚、分组和标题中显示
• 导出：支持导出为 Excel 和 PDF，提供模板和服务器端支持
• 滚动：支持标准、虚拟和无限滚动模式
• 行自定义：支持模板、详情视图、拖放、固定和跨行
• 列自定义：支持模板、调整大小、重新排序、冻结和跨列
• 性能：针对大型数据集优化渲染
• 响应式设计：适配不同屏幕尺寸的布局
• 模块系统：基于功能的模块，可减小打包体积

内置 API 的强制规则

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

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

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

方法	所需模块	示例
goToPage()	Page	<Inject services={[Page]} />
sortColumn()	Sort	<Inject services={[Sort]} />
filterByColumn()	Filter	<Inject services={[Filter]} />
addRecord(), deleteRecord()	Edit	<Inject services={[Edit]} />

规则 2：属性与方法——了解两者的区别

• 属性：通过 JSX 属性设置（<GridComponent allowPaging={true} />）
• 方法：通过 ref 调用（gridRef.current.goToPage(2)）
• 不能通过方法设置属性，也不能通过属性调用方法

---

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

---

功能导航指南

入门与设置

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 基本组件初始化
• CSS 导入和主题配置
• 简单的数据绑定示例
• 模块注入

数据管理

📄 阅读： references/data-binding.md

• 使用数组进行本地数据绑定
• 使用 DataManager 处理远程数据
• 加载指示器（Spinner、Shimmer）
• 数据源配置

列配置

📄 阅读： references/columns.md

• 列定义和属性
• 列类型（字符串、数字、日期、布尔值、复选框）
• 列宽和自动适配
• 列模板和自定义渲染
• 列功能（跨列、重新排序、调整大小、冻结）

聚合与汇总

📄 阅读： references/aggregates.md

• 页脚聚合（Sum、Avg、Count、Min、Max 等）
• 分组页脚聚合
• 分组标题聚合
• 自定义聚合函数
• 响应式聚合更新

导航与分页

📄 阅读： references/paging.md

• 启用和配置分页
• 页面大小和导航
• 页面更改事件
• 自定义分页器 UI
• 查询字符串集成

数据排序

📄 阅读： references/sorting.md

• 单列和多列排序
• 排序方向控制
• 初始排序配置
• 自定义比较器
• 禁止对特定列排序

筛选

从这里开始： 📄 阅读 references/filter-setup.md — 启用筛选，选择筛选类型（FilterBar、Menu、Excel、CheckBox）

选择类型：

• 📄 阅读 references/filter-types.md — 全部 3 种筛选类型：FilterBar（内联文本）、Menu（运算符）、Excel（复选框）
• 📄 阅读 references/filter-operators.md — 全部 21+ 个运算符、语法、通配符、AND/OR 逻辑

搜索

📄 阅读： references/searching.md

• Grid 搜索功能
• 跨列全局搜索
• 与筛选集成的搜索
• 区分大小写的搜索选项

数据分组

📄 阅读： references/grouping.md

• 启用按列分组
• 按多个列分组
• 标题模板
• 分组页脚聚合
• 通过延迟加载提升分组性能

选择

📄 阅读： references/selection.md

• 行、单元格、列选择模式
• 复选框选择
• 多项选择处理
• 选择事件和方法
• 编程式选择

编辑

📄 阅读： references/editing.md

• 启用编辑（allowEditing、allowAdding、allowDeleting）
• 编辑模式：Inline、Batch、Dialog
• 编辑触发方式（双击、工具栏、键盘）
• 自定义编辑模板
• 验证规则和错误处理
• 主键配置

⚠️ 键列必须设置 isPrimaryKey={true}——否则编辑会静默失败。

行功能

📄 阅读： references/row.md

• 行模板
• 详细信息模板（展开/折叠）
• 行拖放
• 行固定
• 行跨越
• 行选择和事件

导出

📄 阅读： references/excel-export.md

• 基本的 Excel 导出功能
• 导出选项和配置
• 使用列模板导出
• 服务端导出
• 导出格式和样式

📄 阅读： references/pdf-export.md

• PDF 导出设置
• 页眉和页脚
• 导出选项和自定义
• 使用模板导出
• 服务端 PDF 导出
• 页面方向和尺寸

滚动模式

📄 阅读： references/scrolling.md

• 标准滚动
• 虚拟滚动（性能优化）
• 无限滚动
• 滚动条自定义
• 高度和宽度配置

⚠️ 必须设置 height——否则滚动会被静默禁用。虚拟滚动和无限滚动模式下，请勿与 allowPaging 组合使用。

行数	模式	关键配置
< 1,000	allowPaging	Page 模块
1K – 100K	enableVirtualization + height	VirtualScroll，不启用分页
连续滚动	enableInfiniteScrolling + height	InfiniteScroll
100K+ 分组数据	enableVirtualization + lazyLoadGrouping	VirtualScroll、Group

冻结与固定

📄 阅读： references/frozen.md

• 冻结列
• 冻结行
• 冻结表头
• 固定行
• 冻结列行为

工具栏

📄 阅读： references/toolbar.md

• 内置工具栏项
• 自定义工具栏按钮
• 工具栏图标和事件
• 编辑工具栏集成
• 工具栏项模板

上下文菜单

📄 阅读： references/context-menu.md

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

单元格操作

📄 阅读： references/cell.md

• 单元格编辑和选择
• 单元格模板
• 单元格值格式化
• 单元格范围和操作
• 单元格焦点和导航

📄 阅读： references/clipboard.md

• 复制和粘贴功能
• 剪贴板事件
• 自定义剪贴板操作
• 复制列标题
• 从外部来源粘贴

打印

📄 阅读： references/print.md

• 打印网格
• 打印模板
• 打印自定义
• 打印指定行/列
• 打印方向和尺寸

样式与外观

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

• CSS 自定义
• 主题（Material、Bootstrap、Fabric）
• 深色模式支持
• 内联样式和类
• 自定义配色方案
• 组件尺寸模式

⚠️ rowDataBound 和 queryCellInfo 会在每次渲染时触发——不要在其中调用 API。 ❌ 切勿同时为同一字段添加列 template 和 rowDataBound 处理程序——这会产生重复且相互冲突的样式逻辑。

层级结构与嵌套数据

📄 阅读： references/hierarchy-grid.md

• 父子数据结构
• 子网格
• 展开和折叠行为
• 嵌套网格模板
• 详细信息行模板
• 层级数据配置

自适应模式

📄 阅读： references/adaptive.md

• enableAdaptiveUI：以全屏模式呈现筛选、排序、列选择器和编辑对话框，以提升移动设备上的易用性。将 e-bigger 类应用于父元素。
• 垂直行呈现：设置 rowRenderingMode="Vertical"，以垂直而非水平方式显示行元素（默认值为 Horizontal）。
• 垂直呈现功能：支持分页、排序、筛选、选择、对话框编辑、汇总、无限滚动和工具栏选项。
• rowRenderingMode 注意事项：列菜单（分组、排序、自适应列宽、筛选、列选择器）仅在 Horizontal 模式下有效。
• AdaptiveUIMode 属性：使用 "Mobile" 仅在移动设备屏幕上呈现自适应布局，或使用 "Both"（默认值）同时适用于移动设备和桌面设备。
• 移动设备屏幕优化：启用 enableAdaptiveUI 后，自动呈现自适应对话框和垂直布局。

配置管理

📄 阅读： references/global-local.md

• 全局网格设置
• 本地列配置
• 配置优先级
• 配置合并

📄 阅读： references/state-management.md

• 持久化网格状态
• 手动保存和恢复网格状态
• 将网格恢复到初始状态
• 防止特定属性被持久化
• 持久化列模板和标题文本

⚠️ 规则：使用网格状态管理时，必须启用 enablePersistence={true}。

模块系统与架构

📄 阅读： references/modules.md

• 网格模块架构和基于功能的模块
• 30 多个可用模块及其依赖项
• 模块注入模式
• 功能与模块的映射
• 包优化和延迟加载
• 按条件加载模块
• Syncfusion React Grid 中的每项功能都需要通过 <Inject services={[...]} /> 显式注入模块。如果未注入，该功能会被静默忽略，不会抛出错误。

⚠️ 规则：<Inject services={[...]} /> 必须是 <GridComponent> 内的最后一个子元素。

数据连接与适配器

📄 阅读： references/adaptors.md

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

性能优化

📄 阅读： references/performance.md

• 针对 10,000 多条记录的虚拟滚动
• 无限滚动和渐进式加载
• 内存管理和清理策略
• 包体积优化
• 事件防抖和节流
• 性能基准测试与监控

无障碍与合规性

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 和 Section 508 标准
• WAI-ARIA 实现和屏幕阅读器
• 键盘导航（Tab、方向键、Enter、Escape）
• 颜色对比度和焦点管理
• 无障碍测试工具（axe、NVDA、JAWS）
• 语义化 HTML 实践

数据验证

📄 阅读： references/validation.md

• 内置验证器（必填、最小值、最大值、模式）
• 自定义验证函数
• 使用服务器检查进行异步验证
• 验证事件和错误显示
• 使用 ASP.NET 进行服务器端验证
• 按列类型设置验证规则

命令列与行操作

📄 阅读： references/command-column.md

• 内置命令（编辑、删除、保存、取消）
• 自定义命令按钮
• 基于角色和状态的命令
• 命令点击事件
• 有条件地显示命令
• CSS 样式和图标

本地化与国际化

📄 阅读： references/localization.md

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

响应式设计与移动设备

📄 阅读： references/responsive-design.md

• 适配手机、平板和桌面的 UI
• 响应式媒体查询与断点
• 列可见性隐藏规则
• 触控交互（滑动、长按）
• 移动设备优化策略
• 特定设备的样式模式

API 参考与属性

📄 阅读： references/properties-configuration.md

• 按类别整理的全部 95+ 项可配置属性
• 便于快速查找的速查表
• 各属性的适用场景
• 各属性所需的模块

程序化控制（方法）

📄 阅读： references/programmatic-api.md

• 按类别整理的全部 137+ 个 Grid 方法（数据、行、列、排序、筛选、分组、分页、编辑、导出）
• 方法签名和参数
• 返回值和用法模式
• 各方法所需的模块

事件通信（事件）

📄 阅读： references/events-catalog.md

• 全部 65+ 个 Grid 事件及其触发时机和使用场景
• 将 actionBegin 接入逻辑，在操作前取消或修改数据（args.cancel = true、args.data.field = value）
• 将 actionComplete 接入逻辑，在操作后作出响应（API 调用、Toast 提示、刷新、恢复工具栏）
• 必须接入 actionFailure 以处理错误
• 使用 args.requestType 识别操作

高级模式与真实场景

📄 实时更新： references/real-time-updates.md

• 自动刷新、WebSocket 和 SignalR 集成模式
• 推送与拉取数据策略
• 连接管理与重连逻辑

📄 性能监控： references/performance-monitoring.md

• 测量 Grid 操作耗时
• 找出渲染瓶颈
• 优化检查清单
• 内存使用情况跟踪

📄 测试 Grid： references/testing-grids.md

• 使用 Jest 和 React Testing Library 进行单元测试
• 集成测试场景
• 快照测试
• Grid 测试最佳实践

快速入门示例

import { ColumnDirective, ColumnsDirective, GridComponent, Inject, Page, Sort, Filter } from '@syncfusion/ej2-react-grids';
import React from 'react';
import '../styles/App.css';

const gridRef = useRef<GridComponent | null>(null);
// Sample data
const data = [
  {
    OrderID: 10248,
    CustomerID: 'VINET',
    EmployeeID: 5,
    OrderDate: new Date(1996, 6, 4)
  },
  {
    OrderID: 10249,
    CustomerID: 'TOMSP',
    EmployeeID: 6,
    OrderDate: new Date(1996, 6, 5)
  },
];

function App() {
  return (
    <GridComponent
      ref={gridRef}
      dataSource={data}
      allowPaging={true}
      allowSorting={true}
      allowFiltering={true}
      pageSettings={{ pageSize: 10 }}
    >
      <ColumnsDirective>
        <ColumnDirective field='OrderID' headerText='Order ID' width='100' textAlign='Right' />
        <ColumnDirective field='CustomerID' headerText='Customer' width='120' />
        <ColumnDirective field='OrderDate' headerText='Order Date' width='130' type='date' format='yMd' />
      </ColumnsDirective>
      <Inject services={[Page, Sort, Filter]} />
    </GridComponent>
  );
}

export default App;