syncfusion-react-grid

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Syncfusion React Grid

Syncfusion React Grid

The Syncfusion React Grid is a comprehensive, feature-rich component for displaying and manipulating tabular data. It provides extensive functionality for data binding, paging, sorting, filtering, grouping, editing, exporting, scrolling modes, row/column customization, and advanced state management to handle datasets of any size and complexity efficiently.
Syncfusion React Grid是一个功能全面、特性丰富的组件,用于展示和操作表格数据。它提供了数据绑定、分页、排序、筛选、分组、编辑、导出、滚动模式、行/列自定义以及高级状态管理等广泛功能,可高效处理任意规模和复杂度的数据集。

Table of Contents

目录

When to Use This Skill

何时使用该技能

Use the Syncfusion React Grid when you need to:
  • Display tabular data with rows and columns in a React application
  • Handle large datasets efficiently with paging, virtual scrolling, or infinite scrolling
  • Enable sorting, filtering, and searching for single or multiple columns
  • Edit data inline with multiple edit modes (Inline, Batch, Dialog)
  • Export data to Excel or PDF formats with customization
  • Group and aggregate data with summaries and calculations
  • Customize rows and cells with templates and styling
  • Manage complex column configurations (frozen columns, spanning, reordering, resizing)
  • Optimize performance when rendering thousands of records
  • Persist grid state for user preferences and configuration
  • Provide responsive data views for different screen sizes
在以下场景中使用Syncfusion React Grid:
  • 在React应用中展示表格数据(行和列形式)
  • 通过分页、虚拟滚动或无限滚动高效处理大型数据集
  • 为单列或多列启用排序、筛选和搜索功能
  • 通过多种编辑模式(内联、批量、对话框)在线编辑数据
  • 自定义配置后将数据导出为Excel或PDF格式
  • 通过汇总和计算对数据进行分组和聚合
  • 使用模板和样式自定义行和单元格
  • 管理复杂列配置(冻结列、列合并、列重排、列调整大小)
  • 渲染数千条记录时优化性能
  • 持久化网格状态以保存用户偏好和配置
  • 为不同屏幕尺寸提供响应式数据视图

Component Overview

组件概述

The Grid component provides:
  • Data Binding: Support for local arrays, remote data sources, and DataManager integration
  • Paging: Client-side pagination with customizable page size and navigation
  • Sorting: Single and multi-column sorting with custom comparers
  • Filtering: Multiple filter modes (Filter Bar, Filter Menu, Excel-like filter)
  • Searching: Global search across columns
  • Grouping: Group data by columns with aggregates and lazy loading
  • Selection: Row, cell, and column selection with checkbox support
  • Editing: Inline, Batch, and Dialog modes with validation and templates
  • Aggregates: Sum, Average, Count, Min, Max with footer, group, and caption display
  • Exporting: Excel and PDF export with templates and server-side support
  • Scrolling: Standard, Virtual, and Infinite scrolling modes
  • Row Customization: Templates, detail views, drag-drop, pinning, spanning
  • Column Customization: Templates, resizing, reordering, freezing, spanning
  • Performance: Optimized rendering for large datasets
  • Responsive Design: Adaptive layouts for different screen sizes
  • Module System: Feature-based modules to reduce bundle size
Grid组件提供以下功能:
  • 数据绑定:支持本地数组、远程数据源和DataManager集成
  • 分页:客户端分页,支持自定义每页条数和导航
  • 排序:单列和多列排序,支持自定义比较器
  • 筛选:多种筛选模式(筛选栏、筛选菜单类、Excel式筛选)
  • 搜索:跨列全局搜索
  • 分组:按列分组数据,支持聚合和懒加载
  • 选择:行、单元格和列选择,支持复选框
  • 编辑:内联、批量和对话框模式,支持验证和模板
  • 聚合:求和、平均值、计数、最小值、最大值,支持页脚、组页脚和组标题展示
  • 导出:Excel和PDF导出,支持模板和服务端导出
  • 滚动:标准滚动、虚拟滚动和无限滚动模式
  • 行自定义:模板、详情视图、拖拽、固定、合并
  • 列自定义:模板、调整大小、重排、冻结、合并
  • 性能:针对大型数据集优化渲染
  • 响应式设计:适配不同屏幕尺寸的布局
  • 模块系统:基于特性的模块,减少包体积

Mandatory Rules for Inbuilt API

内置API的强制规则

CRITICAL: Follow these rules when using Grid's inbuilt API (137+ methods, 65+ events, 95+ properties):
重要提示:使用Grid的内置API(137+方法、65+事件、95+属性)时,请遵循以下规则:

Rule 1: Module Injection Required for Feature Methods

规则1:特性方法需要注入对应模块

Methods only work if their module is injected. No error thrown if module missing.
MethodRequired ModuleExample
goToPage()
Page
<Inject services={[Page]} />
sortColumn()
Sort
<Inject services={[Sort]} />
filterByColumn()
Filter
<Inject services={[Filter]} />
addRecord()
,
deleteRecord()
Edit
<Inject services={[Edit]} />
方法仅在注入对应模块后才能生效。若模块缺失,不会抛出错误。
方法所需模块示例
goToPage()
Page
<Inject services={[Page]} />
sortColumn()
Sort
<Inject services={[Sort]} />
filterByColumn()
Filter
<Inject services={[Filter]} />
addRecord()
,
deleteRecord()
Edit
<Inject services={[Edit]} />

Rule 2: Properties vs Methods - Know the Difference

规则2:区分属性与方法

  • Properties: Set via JSX props (
    <GridComponent allowPaging={true} />
    )
  • Methods: Call via ref (
    gridRef.current.goToPage(2)
    )
  • Can't set properties via methods or call methods via props

📄 Full API Reference: references/grid-properties-methods-events.md
📄 Backend Integration: references/adaptors.md

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

📄 完整API参考: references/grid-properties-methods-events.md
📄 后端集成: references/adaptors.md

Documentation Navigation Guide

文档导航指南

Getting Started & Setup

入门与设置

📄 Read: references/getting-started.md
  • Installation and package setup
  • Basic component initialization
  • CSS imports and theme configuration
  • Simple data binding example
  • Module injection
📄 阅读: references/getting-started.md
  • 安装与包配置
  • 基础组件初始化
  • CSS导入与主题配置
  • 简单数据绑定示例
  • 模块注入

Data Management

数据管理

📄 Read: references/data-binding.md
  • Local data binding with arrays
  • Remote data with DataManager
  • Loading indicators (Spinner, Shimmer)
  • Data source configuration
📄 阅读: references/data-binding.md
  • 本地数组数据绑定
  • 结合DataManager的远程数据
  • 加载指示器(加载动画、骨架屏)
  • 数据源配置

Column Configuration

列配置

📄 Read: references/columns.md
  • Column definition and properties
  • Column types (string, number, date, boolean, checkbox)
  • Column width and auto-fit
  • Column templates and custom rendering
  • Column features (spanning, reordering, resizing, freezing)
📄 阅读: references/columns.md
  • 列定义与属性
  • 列类型(字符串、数字、日期、布尔值、复选框)
  • 列宽与自动适配
  • 列模板与自定义渲染
  • 列特性(合并、重排、调整大小、冻结)

Aggregation & Summaries

聚合与汇总

📄 Read: references/aggregates.md
  • Footer aggregates (Sum, Avg, Count, Min, Max, etc.)
  • Group footer aggregates
  • Group caption aggregates
  • Custom aggregate functions
  • Reactive aggregate updates
📄 阅读: references/aggregates.md
  • 页脚聚合(求和、平均值、计数、最小值、最大值等)
  • 组页脚聚合
  • 组标题聚合
  • 自定义聚合函数
  • 响应式聚合更新

Navigation & Pagination

导航与分页

📄 Read: references/paging.md
  • Enable and configure paging
  • Page size and navigation
  • Page change events
  • Customizing pager UI
  • Query string integration
📄 阅读: references/paging.md
  • 启用并配置分页
  • 每页条数与导航
  • 页码变更事件
  • 自定义分页器UI
  • 查询字符串集成

Sorting Data

数据排序

📄 Read: references/sorting.md
  • Single and multi-column sorting
  • Sort direction control
  • Initial sort configuration
  • Custom comparers
  • Prevent sorting for specific columns
📄 阅读: references/sorting.md
  • 单列和多列排序
  • 排序方向控制
  • 初始排序配置
  • 自定义比较器
  • 禁止特定列排序

Filtering & Searching

筛选与搜索

📄 Read: references/filtering.md
  • Filter bar, filter menu, Excel-like filter modes
  • Filter conditions and operators
  • Composite filtering
  • Filter templates
  • Remote filtering
📄 Read: references/searching.md
  • Grid search functionality
  • Global search across columns
  • Search with filter integration
  • Case-sensitive search options
📄 阅读: references/filtering.md
  • 筛选栏、筛选菜单、Excel式筛选模式
  • 筛选条件与操作符
  • 复合筛选
  • 筛选模板
  • 远程筛选
📄 阅读: references/searching.md
  • Grid搜索功能
  • 跨列全局搜索
  • 搜索与筛选集成
  • 区分大小写的搜索选项

Grouping Data

数据分组

📄 Read: references/grouping.md
  • Enable grouping by columns
  • Group by multiple columns
  • Caption templates
  • Group footer aggregates
  • Lazy-load grouping for performance
📄 阅读: references/grouping.md
  • 启用按列分组
  • 多列分组
  • 标题模板
  • 组页脚聚合
  • 懒加载分组以提升性能

Selection

选择

📄 Read: references/selection.md
  • Row, cell, column selection modes
  • Checkbox selection
  • Multiple selection handling
  • Selection events and methods
  • Programmatic selection
📄 阅读: references/selection.md
  • 行、单元格、列选择模式
  • 复选框选择
  • 多选处理
  • 选择事件与方法
  • 程序化选择

Editing

编辑

📄 Read: references/editing.md
  • Enable editing (allowEditing, allowAdding, allowDeleting)
  • Edit modes: Inline, Batch, Dialog
  • Edit triggers (double-click, toolbar, keyboard)
  • Custom edit templates
  • Validation rules and error handling
  • Primary key configuration
⚠️
isPrimaryKey={true}
is required on the key column — editing silently fails without it.
📄 阅读: references/editing.md
  • 启用编辑(allowEditing、allowAdding、allowDeleting)
  • 编辑模式:内联、批量、对话框
  • 编辑触发方式(双击、工具栏、键盘)
  • 自定义编辑模板
  • 验证规则与错误处理
  • 主键配置
⚠️ 主键列必须设置
isPrimaryKey={true}
—— 若未设置,编辑会静默失败。

Row Features

行特性

📄 Read: references/row.md
  • Row templates
  • Detail templates (expand/collapse)
  • Row drag and drop
  • Row pinning
  • Row spanning
  • Row selection and events
📄 阅读: references/row.md
  • 行模板
  • 详情模板(展开/折叠)
  • 行拖拽
  • 行固定
  • 行合并
  • 行选择与事件

Exporting

导出

📄 Read: references/excel-export.md
  • Basic Excel export functionality
  • Export options and configuration
  • Exporting with column templates
  • Server-side export
  • Formatting and styling in exports
📄 Read: references/pdf-export.md
  • PDF export setup
  • Headers and footers
  • Export options and customization
  • Exporting with templates
  • Server-side PDF export
  • Page orientation and sizing
📄 阅读: references/excel-export.md
  • 基础Excel导出功能
  • 导出选项与配置
  • 带列模板的导出
  • 服务端导出
  • 导出格式与样式
📄 阅读: references/pdf-export.md
  • PDF导出设置
  • 页眉与页脚
  • 导出选项与自定义
  • 带模板的导出
  • 服务端PDF导出
  • 页面方向与尺寸

Scrolling Modes

滚动模式

📄 Read: references/scrolling.md
  • Standard scrolling
  • Virtual scrolling (performance optimization)
  • Infinite scrolling
  • Scrollbar customization
  • Height and width configuration
⚠️
height
is required — scroll is silently disabled without it. Do NOT combine with
allowPaging
in virtual scrolling and infinite scrolling.
RowsModeKey Config
< 1,000
allowPaging
Page
module
1K – 100K
enableVirtualization
+
height
VirtualScroll
, no paging
Continuous
enableInfiniteScrolling
+
height
InfiniteScroll
100K+ grouped
enableVirtualization
+
lazyLoadGrouping
VirtualScroll
,
Group
📄 阅读: references/scrolling.md
  • 标准滚动
  • 虚拟滚动(性能优化)
  • 无限滚动
  • 滚动条自定义
  • 高度与宽度配置
⚠️ 必须设置
height
—— 若未设置,滚动会静默禁用。在虚拟滚动和无限滚动模式下,请勿与
allowPaging
同时使用。
行数模式关键配置
< 1000
allowPaging
Page
模块
1K – 100K
enableVirtualization
+
height
VirtualScroll
,禁用分页
连续加载
enableInfiniteScrolling
+
height
InfiniteScroll
100K+ 分组数据
enableVirtualization
+
lazyLoadGrouping
VirtualScroll
、
Group

Freezing & Pinning

冻结与固定

📄 Read: references/frozen.md
  • Freeze columns
  • Freeze rows
  • Freeze headers
  • Row pinning
  • Frozen column behavior
📄 阅读: references/frozen.md
  • 冻结列
  • 冻结行
  • 冻结表头
  • 行固定
  • 冻结列行为

Toolbar

工具栏

📄 Read: references/toolbar.md
  • Built-in toolbar items
  • Custom toolbar buttons
  • Toolbar icons and events
  • Edit toolbar integration
  • Toolbar item templates
📄 阅读: references/toolbar.md
  • 内置工具栏项
  • 自定义工具栏按钮
  • 工具栏图标与事件
  • 编辑工具栏集成
  • 工具栏项模板

Context Menu

上下文菜单

📄 Read: references/context-menu.md
  • Built-in context menu items
  • Custom context menus
  • Context menu configuration
  • Context menu events
📄 阅读: references/context-menu.md
  • 内置上下文菜单项
  • 自定义上下文菜单
  • 上下文菜单配置
  • 上下文菜单事件

Cell Operations

单元格操作

📄 Read: references/cell.md
  • Cell editing and selection
  • Cell templates
  • Cell value formatting
  • Cell ranges and operations
  • Cell focus and navigation
📄 Read: references/clipboard.md
  • Copy and paste functionality
  • Clipboard events
  • Custom clipboard actions
  • Copy column headers
  • Paste from external sources
📄 阅读: references/cell.md
  • 单元格编辑与选择
  • 单元格模板
  • 单元格值格式化
  • 单元格范围与操作
  • 单元格焦点与导航
📄 阅读: references/clipboard.md
  • 复制粘贴功能
  • 剪贴板事件
  • 自定义剪贴板操作
  • 复制列标题
  • 从外部源粘贴

Printing

打印

📄 Read: references/print.md
  • Print grid
  • Print templates
  • Print customization
  • Print specific rows/columns
  • Print orientation and sizing
📄 阅读: references/print.md
  • 打印Grid
  • 打印模板
  • 打印自定义
  • 打印特定行/列
  • 打印方向与尺寸

Styling & Appearance

样式与外观

📄 Read: references/style-and-appearance.md
  • CSS customization
  • Themes (Material, Bootstrap, Fabric)
  • Dark mode support
  • Inline styling and classes
  • Custom color schemes
  • Component size modes
⚠️
rowDataBound
and
queryCellInfo
fire on every render — no API calls inside them. ❌ Never add both a column
template
and a
rowDataBound
handler targeting the same field — this produces duplicate, conflicting styling logic.
📄 阅读: references/style-and-appearance.md
  • CSS自定义
  • 主题(Material、Bootstrap、Fabric)
  • 深色模式支持
  • 内联样式与类
  • 自定义配色方案
  • 组件尺寸模式
⚠️
rowDataBound
和
queryCellInfo
会在每次渲染时触发 —— 请勿在其中调用API。 ❌ 切勿同时为同一字段设置列
template
和
rowDataBound
处理程序 —— 这会导致重复且冲突的样式逻辑。

Hierarchy & Nested Data

分层与嵌套数据

📄 Read: references/hierarchy-grid.md
  • Parent-child data structures
  • Child grid
  • Expand and collapse behavior
  • Nested grid templates
  • Detail row templates
  • Hierarchical data configuration
📄 阅读: references/hierarchy-grid.md
  • 父子数据结构
  • 子Grid
  • 展开与折叠行为
  • 嵌套Grid模板
  • 详情行模板
  • 分层数据配置

Adaptive Mode

自适应模式

📄 Read: references/adaptive.md
  • enableAdaptiveUI: Render filter, sort, column chooser, and edit dialogs in full-screen mode for better mobile usability. Apply
    e-bigger
    class to parent element.
  • Vertical row rendering: Set
    rowRenderingMode="Vertical"
    to display row elements vertically instead of horizontally (default is Horizontal).
  • Vertical rendering features: Supports paging, sorting, filtering, selection, dialog editing, aggregates, infinite scroll, and toolbar options.
  • rowRenderingMode note: Column Menu (grouping, sorting, autofit, filter, column chooser) only works in Horizontal mode.
  • AdaptiveUIMode property: Use
    "Mobile"
    to render adaptive layout only on mobile screens, or
    "Both"
    (default) for both mobile and desktop.
  • Mobile screen optimization: Render adaptive dialogs and vertical layouts automatically when enableAdaptiveUI is enabled.
📄 阅读: references/adaptive.md
  • enableAdaptiveUI:以全屏模式渲染筛选、排序、列选择器和编辑对话框,提升移动端可用性。为父元素添加
    e-bigger
    类。
  • 垂直行渲染:设置
    rowRenderingMode="Vertical"
    ,将行元素垂直展示(默认是水平展示)。
  • 垂直渲染特性:支持分页、排序、筛选、选择、对话框编辑、聚合、无限滚动和工具栏选项。
  • rowRenderingMode注意事项:列菜单(分组、排序、自动适配、筛选、列选择器)仅在水平模式下生效。
  • AdaptiveUIMode属性:使用
    "Mobile"
    仅在移动端渲染自适应布局,或使用
    "Both"
    (默认)在移动端和桌面端都渲染。
  • 移动端屏幕优化:启用enableAdaptiveUI后,自动渲染自适应对话框和垂直布局。

Configuration Management

配置管理

📄 Read: references/global-local.md
  • Global grid settings
  • Local column configuration
  • Configuration precedence
  • Configuration merging
📄 Read: references/state-management.md
  • Persist grid state
  • Save and restore grid state manually
  • Restore grid to initial state
  • Prevent specific properties from persisting
  • Persist column templates and header text
⚠️ Rule:
enablePersistence={true}
must be enable when use state management in grid.
📄 阅读: references/global-local.md
  • Grid全局设置
  • 列本地配置
  • 配置优先级
  • 配置合并
📄 阅读: references/state-management.md
  • 持久化Grid状态
  • 手动保存和恢复Grid状态
  • 将Grid恢复到初始状态
  • 禁止特定属性持久化
  • 持久化列模板和表头文本
⚠️ 规则:在Grid中使用状态管理时,必须启用
enablePersistence={true}
。

Module System & Architecture

模块系统与架构

📄 Read: references/modules.md
  • Grid module architecture and feature-based modules
  • 30+ available modules and their dependencies
  • Module injection patterns
  • Feature-module mapping
  • Bundle optimization and lazy loading
  • Conditional module loading
  • Every feature in the Syncfusion React Grid requires explicit module injection via
    <Inject services={[...]} />
    . Without injection, the feature is silently ignored — no error is thrown.
⚠️ Rule:
<Inject services={[...]} />
must be the last child inside
<GridComponent>
.
📄 阅读: references/modules.md
  • Grid模块架构和基于特性的模块
  • 30+可用模块及其依赖
  • 模块注入模式
  • 特性-模块映射
  • 包体积优化和懒加载
  • 条件模块加载
  • Syncfusion React Grid的每个功能都需要通过
    <Inject services={[...]} />
    显式注入模块。若未注入,功能会静默失效 —— 不会抛出错误。
⚠️ 规则:
<Inject services={[...]} />
必须是
<GridComponent>
的最后一个子元素。

Data Connectivity & Adaptors

数据连接与适配器

📄 Read: references/adaptors.md
  • 7 adaptor types for backend integration
  • UrlAdaptor, ODataV4Adaptor, WebApiAdaptor, GraphQLAdaptor
  • Custom adaptors and RemoteSaveAdaptor
  • Backend configuration examples (C#, Node.js)
  • Request/response format specifications
  • Error handling and adaptor comparison
📄 阅读: references/adaptors.md
  • 7种适配器类型,用于后端集成
  • UrlAdaptor、ODataV4Adaptor、WebApiAdaptor、GraphQLAdaptor
  • 自定义适配器和RemoteSaveAdaptor
  • 后端配置示例(C#、Node.js)
  • 请求/响应格式规范
  • 错误处理和适配器对比

Performance Optimization

性能优化

📄 Read: references/performance.md
  • Virtual scrolling for 10,000+ records
  • Infinite scrolling and progressive loading
  • Memory management and cleanup strategies
  • Bundle size optimization
  • Event debouncing and throttling
  • Performance benchmarking and monitoring
📄 阅读: references/performance.md
  • 虚拟滚动,支持10,000+条记录
  • 无限滚动和渐进式加载
  • 内存管理和清理策略
  • 包体积优化
  • 事件防抖和节流
  • 性能基准测试和监控

Accessibility & Compliance

可访问性与合规

📄 Read: references/accessibility.md
  • WCAG 2.2 and Section 508 compliance
  • WAI-ARIA implementation and screen readers
  • Keyboard navigation (Tab, arrows, Enter, Escape)
  • Color contrast and focus management
  • Accessibility testing tools (axe, NVDA, JAWS)
  • Semantic HTML practices
📄 阅读: references/accessibility.md
  • 符合WCAG 2.2和Section 508标准
  • WAI-ARIA实现和屏幕阅读器支持
  • 键盘导航(Tab、箭头、Enter、Escape)
  • 颜色对比度和焦点管理
  • 可访问性测试工具(axe、NVDA、JAWS)
  • 语义化HTML实践

Data Validation

数据验证

📄 Read: references/validation.md
  • Built-in validators (required, min, max, pattern)
  • Custom validation functions
  • Async validation with server checks
  • Validation events and error display
  • Server-side validation with ASP.NET
  • Validation rules by column type
📄 阅读: references/validation.md
  • 内置验证器(必填、最小值、最大值、正则)
  • 自定义验证函数
  • 结合服务端检查的异步验证
  • 验证事件和错误展示
  • 服务端验证(ASP.NET)
  • 按列类型配置验证规则

Command Column & Row Actions

命令列与行操作

📄 Read: references/command-column.md
  • Built-in commands (Edit, Delete, Save, Cancel)
  • Custom command buttons
  • Role-based and status-based commands
  • Command click events
  • Conditional command visibility
  • CSS styling and icons
📄 阅读: references/command-column.md
  • 内置命令(编辑、删除、保存、取消)
  • 自定义命令按钮
  • 基于角色和状态的命令
  • 命令点击事件
  • 命令条件可见性
  • CSS样式和图标

Localization & Internationalization

本地化与国际化

📄 Read: references/localization.md
  • Multi-language support (60+ languages)
  • Locale setup and culture configuration
  • Number, date, and currency formatting
  • RTL support (Arabic, Hebrew, Farsi)
  • Custom localization and translation
  • Language switcher implementation
📄 阅读: references/localization.md
  • 多语言支持(60+种语言)
  • 区域设置和文化配置
  • 数字、日期和货币格式化
  • RTL支持(阿拉伯语、希伯来语、波斯语)
  • 自定义本地化和翻译
  • 语言切换器实现

Responsive Design & Mobile

响应式设计与移动端

📄 Read: references/responsive-design.md
  • Adaptive UI for mobile/tablet/desktop
  • Responsive media queries and breakpoints
  • Column visibility hiding rules
  • Touch interactions (swipe, long-press)
  • Mobile optimization strategies
  • Device-specific styling patterns
📄 阅读: references/responsive-design.md
  • 适配移动端/平板/桌面端的UI
  • 响应式媒体查询和断点
  • 列可见性隐藏规则
  • 触摸交互(滑动、长按)
  • 移动端优化策略
  • 设备特定样式模式

Programmatic Control

程序化控制

📄 Read: references/programmatic-api.md
  • The full programmatic method catalog
  • Event prop reference
  • Dynamic column control
  • setProperties()
    examples, export hooks, and cross-feature
📄 阅读: references/programmatic-api.md
  • 完整的程序化方法目录
  • 事件属性参考
  • 动态列控制
  • setProperties()
    示例、导出钩子和跨特性功能

Event Communication

事件通信

📄 Read: references/events-catalog.md
  • Wire
    actionBegin
    to cancel or mutate before an action (
    args.cancel = true
    ,
    args.data.field = value
    )
  • Wire
    actionComplete
    to react after (API call, toast, refresh, toolbar restore)
  • Must wire
    actionFailure
    for error handling
  • Use
    args.requestType
    to identify the action, see the requestType table in the events catalog
📄 阅读: references/events-catalog.md
  • 绑定
    actionBegin
    以取消或在操作前修改(
    args.cancel = true
    、
    args.data.field = value
    )
  • 绑定
    actionComplete
    以在操作后响应(API调用、提示、刷新、工具栏恢复)
  • 必须绑定
    actionFailure
    以处理错误
  • 使用
    args.requestType
    识别操作,详见事件目录中的requestType表格

Advanced Tutorials & Real-World Patterns

高级教程与实战模式

📄 Read: references/advanced-tutorials.md
  • Real-time data updates (WebSocket, SignalR)
  • Master-detail with filtering
  • Complex calculations and running totals
  • Advanced filtering with complex predicates
  • Custom themes and theme switching
  • Performance monitoring techniques
  • Unit and integration testing strategies
📄 阅读: references/advanced-tutorials.md
  • 实时数据更新(WebSocket、SignalR)
  • 主-详情与筛选
  • 复杂计算和运行总计
  • 复杂谓词的高级筛选
  • 自定义主题和主题切换
  • 性能监控技术
  • 单元测试和集成测试策略

Quick Start Example

快速开始示例

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

// 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
      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;
tsx
import { ColumnDirective, ColumnsDirective, GridComponent, Inject, Page, Sort, Filter } from '@syncfusion/ej2-react-grids';
import React from 'react';
import '../styles/App.css';

// 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
      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;

Common Patterns

常见模式

Display & Navigate Large Datasets

展示与导航大型数据集

  1. Set
    allowPaging={true}
    to enable pagination
  2. Configure
    pageSettings.pageSize
    for records per page
  3. Inject the
    Page
    module
  4. For very large datasets (10,000+), use Virtual Scrolling instead
  1. 设置
    allowPaging={true}
    启用分页
  2. 配置
    pageSettings.pageSize
    设置每页记录数
  3. 注入
    Page
    模块
  4. 对于超大型数据集(10,000+条),请使用虚拟滚动替代

Edit Data In-Place

在线编辑数据

  1. Set
    editSettings={{ mode: 'Inline', allowEditing: true, allowAdding: true, allowDeleting: true }}
  2. Set
    isPrimaryKey={true}
    on the primary key column
  3. Inject the
    Edit
    module
  4. Users double-click rows or use toolbar buttons to edit
  1. 设置
    editSettings={{ mode: 'Inline', allowEditing: true, allowAdding: true, allowDeleting: true }}
  2. 在主键列设置
    isPrimaryKey={true}
  3. 注入
    Edit
    模块
  4. 用户可双击行或使用工具栏按钮进行编辑

Export to Excel/PDF

导出为Excel/PDF

  1. Import
    ExcelExport
    or
    PdfExport
    modules
  2. Inject modules into grid
  3. Add toolbar with export buttons
  4. Grid handles export automatically
  1. 导入
    ExcelExport
    或
    PdfExport
    模块
  2. 将模块注入Grid
  3. 添加包含导出按钮的工具栏
  4. Grid会自动处理导出

Group & Summarize Data

分组与汇总数据

  1. Set
    allowGrouping={true}
  2. Inject
    Group
    and
    Aggregate
    modules
  3. Configure
    aggregates
    property with column, type, and templates
  4. Users drag column headers to group area
  1. 设置
    allowGrouping={true}
  2. 注入
    Group
    和
    Aggregate
    模块
  3. 配置
    aggregates
    属性,设置列、类型和模板
  4. 用户可拖拽列标题到分组区域进行分组

High Performance (10,000+ Rows)

高性能处理(10,000+条数据)

  1. Use Virtual Scrolling:
    enableVirtualization={true}
    with
    height
    set
  2. Use Lazy Grouping:
    groupSettings={ lazyLoadGrouping: true }
  3. Use Remote Data with DataManager for server-side operations
  4. Avoid heavy templates; use lightweight rendering
  1. 使用虚拟滚动:
    enableVirtualization={true}
    并设置
    height
  2. 使用懒加载分组:
    groupSettings={ lazyLoadGrouping: true }
  3. 使用结合DataManager的远程数据进行服务端操作
  4. 避免复杂模板,使用轻量渲染

Key Props and Configuration

关键属性与配置

PropertyTypePurposeExample
dataSource
Array | DataManagerData to display
dataSource={data}
allowPaging
booleanEnable pagination
allowPaging={true}
allowSorting
booleanEnable sorting by clicking headers
allowSorting={true}
allowFiltering
booleanEnable filter bar
allowFiltering={true}
allowGrouping
booleanEnable grouping
allowGrouping={true}
editSettings
EditSettingsModelEditing configuration
editSettings={{ mode: 'Dialog', allowEditing: true }}
toolbar
string[]Toolbar items
toolbar={['Add', 'Edit', 'Delete', 'Update', 'Cancel']}

属性类型用途示例
dataSource
Array | DataManager要展示的数据
dataSource={data}
allowPaging
boolean启用分页
allowPaging={true}
allowSorting
boolean启用点击表头排序
allowSorting={true}
allowFiltering
boolean启用筛选栏
allowFiltering={true}
allowGrouping
boolean启用分组
allowGrouping={true}
editSettings
EditSettingsModel编辑配置
editSettings={{ mode: 'Dialog', allowEditing: true }}
toolbar
string[]工具栏项
toolbar={['Add', 'Edit', 'Delete', 'Update', 'Cancel']}