syncfusion-blazor-datagrid

---

实现 Syncfusion Blazor DataGrid

Syncfusion Blazor DataGrid（SfGrid<TValue>）是一个高性能、功能丰富的组件，可用于显示和操作表格数据。它支持数据绑定、排序、筛选、分组、分页、编辑、选择、聚合、导出、虚拟滚动／无限滚动、模板等功能。

NuGet： Syncfusion.Blazor.Grid + Syncfusion.Blazor.Themes
命名空间： Syncfusion.Blazor.Grids

何时使用此技能

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

• 在 Blazor Server、WebAssembly、Web App 或 MAUI 中设置和配置 DataGrid
• 绑定本地或远程数据（OData、HTTP、SfDataManager）
• 配置列（类型、格式、模板、冻结、重新排序、调整大小、列选择器）
• 实现排序、筛选（FilterBar/Menu/Excel/CheckBox）、搜索或查找并突出显示
• 启用惰性加载分组或标题模板
• 使用自定义模板或 SfPager 配置分页
• 为大型数据集设置虚拟滚动、无限滚动
• 实现编辑（Normal/Dialog/Batch/Cell/Command 列）和验证，包括批量撤销／重做
• 配置选择（行、单元格、复选框），并进行编程控制
• 使用剪贴板复制、AutoFill、粘贴功能，或使用 PasteAsync 通过外部按钮粘贴
• 添加聚合（页脚、分组、标题、响应式）
• 使用行／列模板、详细信息模板、行拖放
• 配置工具栏、上下文菜单、列菜单、列选择器
• 将数据导出为 Excel 或 PDF
• 管理打印功能
• 优化性能（SetRowDataAsync、PreventRender）
• 处理 DataGrid 事件
• 管理状态持久化（EnablePersistence）
• 自定义样式和外观
• 为移动端／响应式布局启用自适应 UI

🔒 强制关键规则

这些规则规定了此技能必须如何运行。必须严格遵守。

1. 目的和职责

你的职责是解读用户以自然语言提出的任何请求，并提供关于 Syncfusion Blazor DataGrid 所有受支持方面的：

• 准确
• 完整
• 经验证的信息

包括：

• 公共 API
• 属性
• 事件
• 功能
• 行为

2. 准确性和 API 合规性

此技能必须：

• 仅使用 Syncfusion DataGrid 官方支持的功能。
• 绝不虚构 API、方法、属性、事件、行为或未来功能。
• 绝不提供不受支持或假设性的代码示例。
• 始终遵循 Syncfusion 官方组件设计模式。

如果某项功能不受支持：

• 明确说明此限制。
• 尽可能建议受支持的替代方案。

3. 解读自然语言请求

当用户的请求不完整时：

• 使用官方 Grid 最佳实践推断合理的假设。
• 补充准确且相关的信息，填补缺失之处。
• 仅在确有必要时请求澄清。

4. 响应质量要求

每次响应都必须：

• 技术准确
• 完整且结构清晰
• 包含所需依赖项和配置说明
• 遵循 Syncfusion API 的实际文档行为
• 避免矛盾或歧义

5. 处理不受支持的用户请求

如果用户请求某项不受支持的功能：

• 明确说明该功能不受支持
• 建议官方替代方案或有效的变通方法
• 绝不模拟或捏造不可能实现的功能

6. 设计模式规范

此技能必须遵循 Syncfusion 官方模式，包括：

• 正确的组件结构（SfGrid、GridColumn、GridEditSettings 等）
• 正确使用异步事件和 API
• 有效的配置属性和枚举
• 受支持的数据绑定方式
• 真实的事件模式和名称

7. 质量、完整性与可靠性

该 Skill MUST：

• 仅使用经过验证且真实存在的 Grid 功能
• 提供可执行且可直接实施的指导
• 确保内容清晰，让用户无需猜测即可照做
• 保持格式简洁、易读且专业

8. 防止幻觉的保障措施

该 Skill MUST NOT：

• 虚构不存在的 API 或行为
• 建议不受支持的模式、功能或配置
• 提供错误、误导性或无法验证的代码
• 描述未记录的内部行为

如有疑问：

• 请求澄清 或
• 明确说明限制

9. 事件名称验证要求

重要： 提供代码示例前，MUST 根据 references/events.md 验证事件名称。所有 Grid 事件 MUST 定义在 <GridEvents> 组件内。

常见错误，请避免：

• ❌ OnSortChange - 不存在。请使用 Sorting、Sorted
• ❌ OnFilterChange - 不存在。请使用 Filtering、Filtered
• ❌ OnPageChange - 不存在。请使用 PageChanging、PageChanged
• ❌ OnGroupChange - 不存在。请使用 Grouping、Grouped

规则： ALWAYS 对照 references/events.md 核实：

• 准确的事件名称（区分大小写）
• 事件参数类型
• 事件是否可取消
• 事件触发时机（操作前／后）

提供事件代码前的验证清单：

1. 检查 references/events.md 中是否存在该事件名称
2. 验证正确的 EventArgs 类型
3. 确认 Cancelable 状态（✅ 或 ❌）
4. 对照 Syncfusion 官方文档进行核实
5. 切勿假设命名惯例（例如 On 前缀、Change 后缀）

---

Grid 事件的严格规则

1. 事件处理程序 MUST 位于 <GridEvents> 组件中

• ✅ 在 <GridEvents TValue="YourType"> 内定义所有事件处理程序
• ✅ 将准确的事件名称用作属性（例如 DataBound、RowSelecting、Grouped）
• ❌ 不要在 <SfGrid> 上使用 @onEventName 语法
• ❌ 不要在任何根元素上定义事件处理程序

2. 正确的事件处理程序签名

• ✅ 事件处理程序使用 async Task
• ✅ 事件处理程序可能具有特定的参数类型（例如 GridEventArgs、RowSelectEventArgs）
• ✅ 某些事件没有参数（例如 DataBound()、Created()）
• ❌ 异步操作不要使用同步 void 方法

3. API 方法调用 MUST NOT 放在生命周期事件中

• ❌ 不要在 OnInitialized() 中调用 API 方法
• ❌ 不要在 OnAfterRenderAsync() 中调用 API 方法
• ❌ 不要在 OnParametersSet() 中调用 API 方法
• ✅ ONLY 在响应用户交互时调用 API 方法（按钮点击、下拉列表更改等）
• ✅ 可以在 GridEvents 处理程序中调用 API 方法

4. 使用 Async/Await 模式

• ✅ 对异步 API 方法始终使用 await
• ✅ 将事件处理程序定义为 async Task
• ✅ 将代码块方法标记为 async Task
• ❌ 异步操作不要使用同步方法调用

5. API 调用必须使用 Grid 引用

• ✅ 使用 @ref="Grid" 获取 Grid 实例
• ✅ 使用该引用调用 API 方法（例如 await Grid.GroupColumnAsync()）
• ❌ 不要在没有引用的情况下尝试调用方法

6. 事件类型必须与 GridEvents TValue 匹配

• ✅ 设置 TValue="YourDataType"，使其与数据模型匹配
• ✅ 所有事件处理程序都会使用此模型进行正确的类型化
• ❌ 不要为 TValue 使用泛型或错误的类型

---

导航指南

设置与入门

📄 阅读： references/getting-started.md

• NuGet 安装、_Imports.razor、Program.cs、主题／脚本设置、基本 Grid

📄 阅读： references/getting-started-app-types.md

• Server App、Web App（Auto/WASM）、MAUI 变体

数据

📄 阅读： references/data-binding.md

• 本地（List、ExpandoObject、DynamicObject、DataTable、ObservableCollection）

连接到适配器（远程数据）

📄 阅读： references/odatav4-adaptor.md

• OData V4 服务设置、ODataConventionModelBuilder、[EnableQuery]、自动执行 $filter/$orderby/$skip/$top、使用 PATCH/DELETE 进行 CRUD

📄 阅读： references/web-api-adaptor.md

• Web API 的 { Items, Count } 响应、手动解析 $filter/$orderby/$skip/$top QueryString、使用 GET/POST/PUT/DELETE 进行 CRUD
• **安全提示：**切勿将 SfDataManager.Url 绑定到任意用户提供的 URL。请使用由操作员配置的字符串变量（例如 Url="@DataApiUrl"，其中 DataApiUrl 从配置中的 ALLOWED_API_URL 读取），内部代理/网关、字段/操作符白名单，以及服务器端验证/清理。示例请参阅 references/web-api-adaptor.md 中的 Security Considerations。

📄 阅读： references/url-adaptor.md

• 自定义 API 的 { result, count } 响应、DataManagerRequest POST 请求体、DataOperations 辅助方法、InsertUrl/UpdateUrl/RemoveUrl/CrudUrl/BatchUrl
• **安全提示：**使用由配置提供的 URL 变量（例如 Url="@DataApiUrl"，其中 DataApiUrl 从配置中的 ALLOWED_API_URL 读取），避免使用用户提供的端点，并通过内部代理/网关路由第三方请求。示例和配置片段请参阅 references/url-adaptor.md。

📄 阅读： references/custom-adaptor.md

• DataAdaptor 抽象类、重写 Read/Insert/Update/Remove/BatchUpdate、服务注入、将适配器用作组件、通过 Query.AddParams 添加自定义参数
• **安全提示：**实现 CustomAdaptor 时，不要信任 dm.Params 或用户提供的端点。请使用由操作员配置的端点，验证 dm.Params，设置字段/操作符白名单，并通过代理路由第三方调用。示例请参阅 references/custom-adaptor.md 中的 Security Considerations。

列

📄 阅读： references/columns.md

• ColumnType、Format、TextAlign、冻结、重新排序、调整大小、列选择器、堆叠表头、列菜单、外键

📄 阅读： references/cell.md

• QueryCellInfo、CustomAttributes、ClipMode、GridLines、工具提示

排序、筛选、搜索

📄 阅读： references/sorting.md

• AllowSorting、多列排序、SortColumnAsync、ClearSortingAsync

📄 阅读： references/filtering.md

• AllowFiltering、FilterType（FilterBar/Menu/Excel/CheckBox）、操作符、FilterByColumnAsync

📄 阅读： references/searching.md

• 工具栏搜索、SearchAsync、GridSearchSettings

📄 阅读： references/find-highlight.md

• 查找和高亮工具栏、GridFindSettings、AllowSearchHighlight、FindHighlightAsync / FindNextHighlightAsync / FindPreviousHighlightAsync / FindGoToAsync / ResetFindAsync

分组与分页

📄 阅读： references/grouping.md

• AllowGrouping、延迟加载分组、CaptionTemplate、以编程方式分组/取消分组

📄 阅读： references/paging.md

• AllowPaging、GridPageSettings、分页器模板、GoToPageAsync

滚动

📄 阅读： references/scrolling.md

• Height/Width、粘性表头、ScrollIntoViewAsync

📄 阅读： references/virtual-scrolling.md

• EnableVirtualization、EnableColumnVirtualization、OverscanCount、限制

📄 阅读： references/infinite-scrolling.md

• EnableInfiniteScrolling、GridInfiniteScrollSettings、缓存模式、限制

编辑

📄 阅读： references/editing.md

• GridEditSettings、EditMode（Normal/Dialog/Batch/Cell/CommandColumn）、ValidationRules、EditType、EditTemplate、CRUD 方法、AllowEditOnKeyPress、EnterKeyDirection、EnableUndoRedo、UndoRedoLimit

阅读： references/editing-patterns.md

• 根据条件取消编辑、禁用特定行的编辑
• 通过事件提供新建/已编辑的项、列默认值、新行位置
• 始终显示新增行表单、删除多行、单击编辑
• 在指定索引处保存新行、内联模板编辑
• 批量撤销 / 重做（EnableUndoRedo、UndoRedoLimit、UndoAsync/RedoAsync、OnUndo/OnRedo 事件）

📄 阅读： references/editing-validation.md

• 按列设置 ValidationRules、Data Annotation 特性（[Required]、[Range] 等）
• 自定义验证特性、复杂类型验证、自定义验证器组件

选择

📄 阅读： references/selection.md

• AllowSelection、SelectionMode、SelectionType、复选框选择、以编程方式选择

📄 阅读： references/clipboard.md

• 剪贴板复制（Ctrl+C / Ctrl+Shift+H）、CopyAsync、自动填充拖动手柄、粘贴（Ctrl+V）、通过外部按钮使用 PasteAsync、批量编辑要求

汇总

📄 阅读： references/aggregates.md

• GridAggregates、AggregateType、FooterTemplate、GroupFooterTemplate、GroupCaptionTemplate、响应式汇总

行功能与模板

📄 阅读： references/row-features.md

• RowDataBound、行拖放、行高、行跨列、RowTemplate

📄阅读： references/templates-structural.md

• ColumnTemplate（图像、超链接、复选框、SfChip）、HeaderTemplate、RowTemplate、RowTemplate 格式设置、DetailTemplate、展开/折叠 API、加载时展开、隐藏展开图标、自定义 CSS 图标、分层嵌套 Grid

📄 阅读： references/templates-interactive.md

• ToolbarTemplate、列 EditTemplate、GridEditSettings Template、新增与编辑时禁用输入项、三级下划线嵌套绑定、对话框打开时聚焦编辑器、RowUpdating 转换、FooterTemplate、CaptionTemplate、标题中的自定义 Blazor 组件、本地化自定义、PagerTemplate

工具栏、上下文菜单

📄 阅读： references/toolbar.md

• 内置/自定义工具栏项、OnToolbarClick、ToolbarTemplate

📄 阅读： references/context-menu.md

• ContextMenuItems、自定义项、ContextMenuItemClicked

导出与打印

📄 阅读： references/excel-export.md

• AllowExcelExport、ExportToExcelAsync、ExcelExportProperties、主题/模板导出

📄 阅读： references/pdf-export.md

• AllowPdfExport、ExportToPdfAsync、PdfExportProperties、模板 PDF 导出

📄 阅读： references/print.md

• PrintAsync、PrintMode

性能、事件、状态

📄 阅读： references/performance.md

• SetRowDataAsync、PreventRender、WebAssembly 优化、列虚拟化提示

📄 阅读： references/events.md

• GridEvents 完整参考：所有编辑、选择、筛选、排序、分组、分页、工具栏、导出事件

📄 阅读： references/state-management.md

• EnablePersistence、GetPersistDataAsync、SetPersistDataAsync、ResetPersistDataAsync

样式与自适应 UI

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

• Grid、标题、行、筛选、编辑、分组、汇总的 CSS 类

📄 阅读： references/adaptive-layout.md

• EnableAdaptiveUI、RowRenderingMode、AdaptiveUIMode、移动设备响应式模式

快速开始

@page "/datagrid-demo"
@using Syncfusion.Blazor.Grids

<SfGrid DataSource="@Orders" AllowPaging="true" AllowSorting="true" AllowFiltering="true">
    <GridPageSettings PageSize="10"></GridPageSettings>
    <GridColumns>
        <GridColumn Field="OrderID"    HeaderText="Order ID"   IsPrimaryKey="true" Width="120" TextAlign="TextAlign.Right"></GridColumn>
        <GridColumn Field="CustomerID" HeaderText="Customer"   Width="150"></GridColumn>
        <GridColumn Field="Freight"    HeaderText="Freight"    Format="C2" Width="120" TextAlign="TextAlign.Right"></GridColumn>
        <GridColumn Field="OrderDate"  HeaderText="Order Date" Format="d"  Width="150" Type="ColumnType.Date"></GridColumn>
        <GridColumn Field="ShipCountry" HeaderText="Ship Country" Width="150"></GridColumn>
    </GridColumns>
</SfGrid>

@code {
    public List<Order> Orders = new List<Order>
    {
        new Order { OrderID = 10248, CustomerID = "VINET", Freight = 32.38, OrderDate = new DateTime(1996,7,4), ShipCountry = "France" },
        new Order { OrderID = 10249, CustomerID = "TOMSP", Freight = 11.61, OrderDate = new DateTime(1996,7,5), ShipCountry = "Germany" },
    };
    public class Order
    {
        public int OrderID { get; set; }
        public string CustomerID { get; set; }
        public double Freight { get; set; }
        public DateTime OrderDate { get; set; }
        public string ShipCountry { get; set; }
    }
}

常见模式

带编辑和工具栏的网格

<SfGrid DataSource="@Orders" Toolbar="@(new List<string>() { "Add","Edit","Delete","Update","Cancel" })">
    <GridEditSettings AllowAdding="true" AllowEditing="true" AllowDeleting="true" Mode="EditMode.Normal"></GridEditSettings>
    <GridColumns>
        <GridColumn Field="OrderID" IsPrimaryKey="true" ValidationRules="@(new ValidationRules{Required=true})"></GridColumn>
        <GridColumn Field="CustomerID" ValidationRules="@(new ValidationRules{Required=true})"></GridColumn>
        <GridColumn Field="Freight" EditType="EditType.NumericEdit"></GridColumn>
    </GridColumns>
</SfGrid>

带分组和分页的网格

<SfGrid DataSource="@Orders" AllowGrouping="true" AllowPaging="true">
    <GridGroupSettings Columns="@(new string[]{"ShipCountry"})"></GridGroupSettings>
    <GridPageSettings PageSize="10"></GridPageSettings>
    <GridColumns>
        <GridColumn Field="OrderID" Width="120"></GridColumn>
        <GridColumn Field="CustomerID" Width="150"></GridColumn>
        <GridColumn Field="ShipCountry" Width="150"></GridColumn>
    </GridColumns>
</SfGrid>

用于程序化控制的网格引用

<SfGrid @ref="Grid" DataSource="@Orders">...</SfGrid>
@code {
    SfGrid<Order> Grid;
    // Programmatic operations:
    // await Grid.SortColumnAsync("OrderID", SortDirection.Ascending, false);
    // await Grid.FilterByColumnAsync("ShipCountry", "equal", "France");
    // await Grid.GoToPageAsync(2);
    // await Grid.StartEditAsync();
    // await Grid.SelectRowAsync(0);
}

关键属性一览

属性	说明
DataSource	绑定 IEnumerable<T> 或 DataManagerRequest
AllowPaging	启用分页
AllowSorting	启用排序
AllowFiltering	启用列筛选
AllowGrouping	启用行分组
AllowSelection	启用行/单元格选择
Height / Width	用于滚动的固定尺寸
Toolbar	内置或自定义工具栏项
EnableVirtualization	对大量数据启用行虚拟化
EnableInfiniteScrolling	启用无限滚动加载
EnablePersistence	将状态保存到 localStorage
EnableAdaptiveUI	启用适配移动设备的渲染