syncfusion-angular-grid

Syncfusion Angular Grid

这是一份全面的指南，介绍如何使用 Syncfusion 的 Angular Grid 组件实现功能强大的数据网格。本技能涵盖网格功能的方方面面，从基本的数据绑定到虚拟滚动、层级数据、状态管理和多格式导出等高级功能。

⚠️ 安全与信任边界

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

目录

• 何时使用此技能
• TreeGrid 与 Grid：选择指南
• 关键 API 规则与要求
• 功能导航指南
• 快速入门示例
• 常见模式
• 关键属性与配置
• 常见用例

何时使用此技能

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

• 显示表格数据 — 以表格形式加载并呈现结构化数据
• 启用数据操作 — 对大型数据集进行排序、筛选、搜索和分页
• 实现编辑功能 — 添加、更新和删除记录，并进行验证
• 自定义列 — 配置列属性、模板和布局
• 导出数据 — 生成 Excel、PDF 或适合打印的报告
• 处理高级场景 — 层级数据、虚拟滚动、状态持久化
• 应用样式 — 设置网格主题、自定义外观和特定元素的样式
• 优化性能 — 为大型数据集实现无限滚动和虚拟滚动

TreeGrid 与 Grid：选择指南

要求	使用 TreeGrid	使用 Grid
数据结构	层级/树形/嵌套	扁平/表格
父子关系	✅ 原生支持	❌ 不支持（使用 Detail Template）
展开/折叠行	✅ 内置	❌ 不支持
嵌套汇总	✅ 包含子项	✅ 仅支持扁平数据
缩进/取消缩进操作	✅ 支持	❌ 不支持
列分组	❌ 不支持（使用 Grid）	✅ 支持
性能（100K+ 行）	✅优秀	✅ 优秀
用例	组织架构图、文件系统、物料清单（BoM）	订单、发票、列表

关键 API 规则与要求

Grid 内置 API（137+ 个方法、65+ 个事件、95+ 个属性）要求严格遵守访问模式：

⚠️ 正确使用 API 的详细规则位于参考指南中 — 请根据需要查看以下部分：

• 📄 属性参考 → references/grid-properties.md — 按类别整理的 95+ 个可配置属性
• 📄 方法参考 → references/grid-methods.md — 用于数据操作、选择、排序、筛选等的 137+ 个方法
• 📄 事件参考 → references/grid-events.md — 用于生命周期管理、用户交互和数据变更的 65+ 个事件
• 📄 编程式控制 → references/programmatic-api.md — 了解 @ViewChild 要求、方法参数、异步处理和刷新模式
• 📄 事件处理 → references/events-catalog.md — 事件签名、时机、取消操作和渲染事件限制
• 📄 模块系统 → references/modules.md — 功能方法的服务注入要求
• 📄 选择 → references/selection.md — 选择方法的前置条件
• 📄 后端集成 → references/adaptors.md

---

功能导航指南

入门与设置

📄 阅读： references/getting-started.md

• 安装和软件包设置
• 基本网格初始化
• CSS 导入和主题
• 最小可运行示例

数据管理

📄 阅读： references/data-binding.md

• 本地和远程数据绑定
• 数据源配置
• API 集成
• 实时数据更新

列配置

📄 阅读： references/columns.md

• 列属性和类型
• 列模板
• 外键列
• 列渲染选项

相关内容 — 高级列功能：
📄 阅读： references/context-menu.md（列的上下文菜单）

行管理与模板

📄 阅读： references/row.md

• 行属性和事件
• 行模板
• 详情行模板
• 行跨列

选择与交互

📄 阅读： references/selection.md

• 行、单元格和列的选择
• 复选框选择
• 选择事件
• 多选模式

数据操作

📄 阅读： references/filtering.md

• 筛选栏和筛选菜单
• 类似 Excel 的筛选
• 自定义筛选器
• 以编程方式筛选

📄 阅读： references/sorting.md

• 单列和多列排序
• 自定义排序顺序
• 排序事件

📄 阅读： references/searching.md

• 全局搜索功能
• 跨列搜索
• 搜索算法

📄 阅读： references/paging.md

• 分页设置
• 页面大小配置
• 页面变更事件

编辑与验证

📄 阅读： references/editing.md

• 编辑类型（行内、对话框、批量）
• 编辑模板和自定义编辑器
• 内置验证器（必填、最小值、最大值、模式）
• 验证规则和错误消息
• 将更改保存到服务器

⚠️ 重要提示： 必须在键列上设置 [isPrimaryKey]="true"，否则编辑会静默失败（不会抛出错误）。

分组与聚合

📄 阅读： references/grouping.md

• 按列分组
• 延迟加载分组
• 标题模板

📄 阅读： references/aggregates.md

• 汇总行
• 自定义聚合函数
• 页脚聚合

导出与报告

📄 阅读： references/excel-export.md

• 导出为 Excel 格式
• 导出选项和自定义设置
• 导出事件

📄 阅读： references/pdf-export.md

• 导出为 PDF
• PDF 模板和格式设置
• 页眉和页脚配置

📄 阅读： references/print.md

• 打印功能
• 打印模板
• 打印事件

样式与 UI 自定义

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

• 主题选择
• CSS 自定义
• 为特定区域设置样式（页眉、行、单元格）
• 自定义 CSS 类

📄 阅读： references/toolbar.md

• 工具栏项和配置
• 自定义工具栏按钮
• 工具栏事件和点击处理程序

📄 阅读： references/clipboard.md

• 复制/粘贴功能
• 剪贴板事件
• 剪贴板选择管理

高级列功能

📄 阅读： references/frozen.md

• 冻结列
• 冻结多列
• 冻结位置配置

⚠️ 性能警告： rowDataBound 和 queryCellInfo 会在每次渲染/滚动时触发——切勿在其中调用 API。 ⚠️ 冲突风险： 不要同时添加针对同一字段的列 [template] 和 rowDataBound 处理程序，否则会产生重复且冲突的样式。

单元格与行功能

📄 阅读： references/cell.md

• 单元格编辑和选择
• 单元格模板
• 单元格跨列
• 单元格级事件

上下文与交互

📄 阅读： references/context-menu.md

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

高级功能

📄 阅读： references/scrolling.md

• 支持 1K–100K+ 条记录的虚拟滚动
• 支持持续加载的无限滚动
• 固定表头
• 滚动性能优化

⚠️ 重要： 必须设置 height，否则滚动会被静默禁用（不会抛出错误）。 ⚠️ 不兼容： 请勿将 enableVirtualization 或 enableInfiniteScrolling 与 allowPaging 组合使用，否则结果不可预测。

行数	模式	关键配置
< 1,000	allowPaging	Page 模块
1K – 100K	enableVirtualization + height	VirtualScroll，不分页
持续加载	enableInfiniteScrolling + height	InfiniteScroll
100K+ 分组	enableVirtualization + lazyLoadGrouping	VirtualScroll，Group

📄 阅读： references/hierarchy-grid.md

• 主从网格
• 子网格配置
• 嵌套/分层数据
• 详情行模板
• 延迟加载子数据

📄 阅读： references/state-management.md

• 保存网格状态（列、排序、筛选器）
• 恢复网格状态
• 状态持久化选项

📄 阅读： references/adaptive.md

• 响应式/移动模式
• 自适应布局
• 触控交互

📄 阅读： references/global-local.md

• 键盘快捷键和导航
• 全局与本地设置
• 无障碍配置

模块系统与架构

📄 阅读： references/modules.md

• 网格模块架构和 23+ 个功能服务
• 服务依赖关系
• 组件装饰器中的模块注入模式
• 通过选择性导入优化打包体积
• 模块引入对性能的影响

数据连接与适配器

📄 阅读： 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

• 内置验证器（required、min、max、pattern）
• 自定义验证函数
• 通过服务器检查进行异步验证
• 验证事件和错误显示
• 使用 ASP.NET 进行服务器端验证
• 按列类型配置验证规则

命令列与行操作

📄 阅读： references/command-column.md

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

本地化与国际化

📄 阅读： references/localization.md

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

响应式设计与移动端

📄 阅读： references/responsive-design.md

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

程序化控制

📄 阅读： references/programmatic-api.md

• 完整的程序化方法目录
• 事件属性参考
• 动态列控制
• setProperties() 示例、导出钩子及跨功能

事件通信

📄 阅读： references/events-catalog.md

• 将 actionBegin 连接到操作前的取消或修改（args.cancel = true、args.data.field = value）
• 将 actionComplete 连接到操作后的响应（API 调用、toast 提示、刷新、工具栏还原）
• 必须连接 actionFailure 以处理错误
• 使用 args.requestType 识别操作，参见事件目录中的 requestType 表格

高级教程与实际应用模式

📄 阅读： references/advanced-tutorials.md

• 实时数据更新（WebSocket、SignalR）
• 带筛选的主从明细
• 复杂计算和累计总计
• 使用复杂谓词进行高级筛选
• 自定义主题和主题切换
• 性能监控技术

API 参考 - 属性

📄 阅读： references/grid-properties.md

• 属性概览
• 核心数据属性
• 按类别组织属性
• 配置参考

API 参考 - 方法

📄 阅读： references/grid-methods.md

• 方法概览
• 数据操作方法
• 方法参数和签名
• 返回类型和异步处理

API 参考 - 事件

📄 阅读： references/grid-events.md

• 事件概览
• 数据事件
• 事件生命周期和时序
• 事件参数和属性

测试与质量保证

📄 阅读： references/test-case.md

• 单元测试
• 集成测试
• 测试策略
• 测试用例示例

快速入门示例

import { Component, OnInit } from '@angular/core';
import { GridComponent } from '@syncfusion/ej2-angular-grids';

interface Employee {
  EmployeeID: number;
  FirstName: string;
  LastName: string;
  Title: string;
  HireDate: Date;
  ReportsTo: number;
  Salary: number;
}

@Component({
  selector: 'app-grid',
  template: `
    <ejs-grid [dataSource]="data" [allowPaging]="true" 
              [pageSettings]="{ pageSize: 12 }"
              [allowSorting]="true" 
              [allowFiltering]="true">
      <e-columns>
        <e-column field="EmployeeID" headerText="ID" width="100"></e-column>
        <e-column field="FirstName" headerText="First Name" width="120"></e-column>
        <e-column field="LastName" headerText="Last Name" width="120"></e-column>
        <e-column field="Title" headerText="Title" width="150"></e-column>
        <e-column field="HireDate" headerText="Hire Date" type="date" 
                  format="yMd" width="130"></e-column>
        <e-column field="Salary" headerText="Salary" type="number" 
                  format="C2" width="120"></e-column>
      </e-columns>
    </ejs-grid>
  `
})
export class GridComponent implements OnInit {
  data: Employee[] = [];

  ngOnInit() {
    this.loadEmployeeData();
  }

  loadEmployeeData() {
    // Load your data here
    this.data = [
      { EmployeeID: 1, FirstName: 'Nancy', LastName: 'Davolio', Title: 'Sales Representative', 
        HireDate: new Date(1992, 4, 1), ReportsTo: 2, Salary: 60000 },
      { EmployeeID: 2, FirstName: 'Andrew', LastName: 'Fuller', Title: 'Vice President Sales', 
        HireDate: new Date(1992, 8, 14), ReportsTo: null, Salary: 97000 },
      // ... more data
    ];
  }
}

常见模式

模式 1：带排序、筛选和分页的数据网格

组合排序、筛选和分页，提供完整的数据探索体验：

<ejs-grid [dataSource]="data" 
          [allowSorting]="true" 
          [allowFiltering]="true" 
          [allowPaging]="true"
          [pageSettings]="{ pageSize: 20 }">
  <e-columns>
    <e-column field="EmployeeID" headerText="ID" width="100"></e-column>
    <e-column field="FirstName" headerText="First Name" width="120"></e-column>
    
  </e-columns>
</ejs-grid>

模式 2：带验证的行内编辑

启用带表单验证的行内编辑：

<ejs-grid [dataSource]="data" 
          [editSettings]="{ allowEditing: true, allowAdding: true, mode: 'Normal' }"
          [toolbar]="['Add', 'Edit', 'Delete', 'Update', 'Cancel']">
  <e-columns>
    <e-column field="EmployeeID" headerText="ID" [isPrimaryKey]="true" 
              width="100"></e-column>
    <e-column field="FirstName" headerText="First Name" 
              [validationRules]="{ required: true }" width="120"></e-column>
    
  </e-columns>
</ejs-grid>

模式 3：导出为 PDF 和 Excel

通过工具栏启用 PDF 和 Excel 导出：

<ejs-grid [dataSource]="data" 
          [toolbar]="['PdfExport', 'ExcelExport']"
          [allowPdfExport]='true'
          [allowExcelExport]='true'
          (toolbarClick)='toolbarClick($event)'>
  <e-columns>
    
  </e-columns>
</ejs-grid>

模式 4：大型数据集的虚拟滚动

使用虚拟滚动优化性能：

<ejs-grid [dataSource]="largeDataset" 
          [enableVirtualization]="true"
          [pageSettings]="{ pageSize: 50 }">
  <e-columns>
    
  </e-columns>
</ejs-grid>

主要属性与配置

属性	类型	用途	常见值
dataSource	Array/DataManager	网格数据	Employee[], RemoteDataBinding
allowSorting	boolean	启用排序	true, false
allowFiltering	boolean	启用筛选	true, false
allowPaging	boolean	启用分页	true, false
allowGrouping	boolean	启用分组	true, false
editSettings	object	编辑配置	{ mode: 'Inline' }
pageSettings	object	分页选项	{ pageSize: 12 }
enableVirtualization	boolean	虚拟滚动	true, false
allowExcelExport	boolean	Excel 导出	true, false
allowPdfExport	boolean	PDF 导出	true, false
toolbar	array	工具栏项	['Add', 'Edit', 'Delete']
columns	array	列定义	[{ field, headerText }]
height	string/number	网格高度	'400px', 'auto'

常见用例

场景 1：员工目录 实现可搜索、可排序、可筛选的员工列表，并按需显示详细信息。
→ 组合：getting-started + data-binding + columns + selection + hierarchy-grid

场景 2：数据录入表单 构建用于添加和编辑记录并支持验证的网格。
→ 组合：editing + validation + toolbar + filtering

场景 3：销售报告仪表板 创建高度自定义的网格，支持分组、汇总和 PDF 导出。
→ 组合：grouping + aggregates + pdf-export + style-and-appearance

场景 4：实时数据监控器 显示支持虚拟滚动和状态持久化的流式数据。
→ 组合：scrolling + state-management + data-binding + adaptive

场景 5：多级组织结构图 展示分层组织结构，并为每个层级提供详细信息行。
→ 组合：hierarchy-grid + row templates + cell styling