syncfusion-blazor-treegrid

实现 Syncfusion Blazor TreeGrid

Syncfusion Blazor TreeGrid（SfTreeGrid<TValue>）以表格形式呈现分层数据，并支持展开和折叠行。它支持自引用的扁平数据（IdMapping/ParentIdMapping）和嵌套子集合，并提供完整的网格功能，包括编辑、筛选、排序、虚拟化和导出。

何时使用此技能

• 用户需要在 Blazor 应用中使用分层／树状数据表
• 用户提到 SfTreeGrid、TreeGrid、IdMapping、ParentIdMapping
• 用户需要在网格中显示支持展开和折叠的父子行
• 用户需要对树状数据执行 CRUD 操作
• 用户需要导出、筛选、排序或分页分层数据
• 用户需要使用 GraphQLAdaptor 将 TreeGrid 绑定到 GraphQL API
• 用户正在以网格形式处理组织架构图、任务层级、物料清单或文件资源管理器风格的数据
• 用户正从扁平 DataGrid 迁移到分层 TreeGrid
• 用户正在 Blazor Web App、WASM、Server 或 MAUI 项目中配置 TreeGrid

触发关键词： TreeGrid、Tree Grid、SfTreeGrid、分层网格、父子网格、IdMapping、ParentIdMapping、树状数据表、嵌套网格行、Syncfusion Blazor tree、GraphQL TreeGrid、GraphQLAdaptor TreeGrid

---

🔒 强制关键规则

这些规则规定了此技能必须如何运行。它们是强制规则，必须严格遵守。

1. 目的与职责

你的职责是解读用户以自然语言提出的任何请求，并就 Syncfusion Blazor TreeGrid 支持的所有方面提供准确、完整且经过验证的信息，包括：

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

2. 准确性与 API 合规性

此技能必须：

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

如果某项功能不受支持：请明确说明限制，并在可能时建议受支持的替代方案。

3. 解读自然语言请求

当用户的请求不完整时：

• 使用官方 TreeGrid 最佳实践推断合理假设。
• 补充缺失的信息，提供准确且相关的内容。
• 仅在必要时请求澄清。

4. 处理用户提出的不受支持的请求

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

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

5. 设计模式约束

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

• 正确的组件结构（SfTreeGrid、TreeGridColumn、TreeGridEditSettings、TreeGridEvents 等）
• 正确使用异步事件和 API
• 有效的配置属性和枚举
• 受支持的数据绑定方式（自引用、分层、远程、自定义适配器、GraphQL）
• 真实有效的事件模式和名称

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

此技能必须：

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

7. 防止幻觉的保障措施

此技能不得：

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

如果不确定：请请求澄清，或明确说明限制。

8. 事件名称验证要求

关键： 提供代码示例之前，必须先对照 references/events.md 验证事件名称。所有树形网格事件都必须定义在 <TreeGridEvents> 组件内

常见错误：

• ❌ OnSortChange — 不存在。请使用 Sorting、Sorted
• ❌ OnFilterChange — 不存在。请使用 Filtering、Filtered

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

• 准确的事件名称（区分大小写）
• 事件参数类型（命名空间解析请参见规则 11）
• 事件是否可取消（✅ 或 ❌）
• 事件触发时机（操作前／后）

9. 编写代码前阅读参考文件

生成任何代码之前，请识别请求中的每项功能，并阅读对应的参考文件。此文件中的代码片段经过了简化，省略了关键规则和已知陷阱。参考文件是权威来源。

⚠️ 阅读所有适用的参考文件，而不只是查询中最明显的那一个。

10. 命名空间和类型解析规则

规则 1： 始终使用完整的命名空间限定，以避免 CS0104“引用不明确”错误。Syncfusion.Blazor.TreeGrid 和 Syncfusion.Blazor.Grids 命名空间中都存在相关类型。

规则 2： 务必在 _Imports.razor 或组件中添加 @using Syncfusion.Blazor.Grids;，以避免以下内容出现 CS0103“缺少引用”错误：

• 事件参数类型（ActionEventArgs、RowDataBoundEventArgs、BeforeCopyPasteEventArgs 等）
• Action 枚举（Action.Sorting、Action.Save 等）
• 组件类（TreeGridPageSettings、TreeGridFilterSettings、TreeGridSelectionSettings 等）
• 事件处理程序支持类

规则 3： 以下事件参数类型属于 Syncfusion.Blazor.TreeGrid — 添加 @using Syncfusion.Blazor.TreeGrid;（而不是 Syncfusion.Blazor.Grids）：

• RowExpandingEventArgs<TValue>、RowExpandedEventArgs<TValue>
• RowCollapsingEventArgs<TValue>、RowCollapsedEventArgs<TValue>
• CheckBoxChangeEventArgs<TValue>

类型参考：

类型	命名空间	示例
FilterType	TreeGrid	Syncfusion.Blazor.TreeGrid.FilterType.Excel
EditMode	TreeGrid	Syncfusion.Blazor.TreeGrid.EditMode.Row
CopyHierarchyType	TreeGrid	Syncfusion.Blazor.TreeGrid.CopyHierarchyType.Both
Action	Grids	Syncfusion.Blazor.Grids.Action.Save
TextAlign	Grids	Syncfusion.Blazor.Grids.TextAlign.Right
ColumnType	Grids	Syncfusion.Blazor.Grids.ColumnType.Date
EditType	Grids	Syncfusion.Blazor.Grids.EditType.DatePickerEdit
SelectionMode	Grids	Syncfusion.Blazor.Grids.SelectionMode.Row
SelectionType	Grids	Syncfusion.Blazor.Grids.SelectionType.Multiple
ClipMode	Grids	Syncfusion.Blazor.Grids.ClipMode.Ellipsis
GridLine	Grids	Syncfusion.Blazor.Grids.GridLine.Horizontal
AggregateType	Grids	Syncfusion.Blazor.Grids.AggregateType.Sum
CellSelectionMode	Grids	Syncfusion.Blazor.Grids.CellSelectionMode.Box

---

组件概述

<SfTreeGrid DataSource="@TreeData"
            IdMapping="TaskId"
            ParentIdMapping="ParentId"
            TreeColumnIndex="1"
            AllowSorting="true"
            AllowFiltering="true"
            AllowPaging="true">
    <TreeGridColumns>
        <TreeGridColumn Field="TaskId" HeaderText="ID" Width="80" IsPrimaryKey="true" />
        <TreeGridColumn Field="TaskName" HeaderText="Task Name" Width="200" />
        <TreeGridColumn Field="Duration" HeaderText="Duration" Width="100" />
        <TreeGridColumn Field="Progress" HeaderText="Progress" Width="100" />
    </TreeGridColumns>
</SfTreeGrid>

关键概念：

• IdMapping — 唯一标识每行的属性名称
• ParentIdMapping — 指向父行 ID 的属性名称（null/0 = 根节点）
• TreeColumnIndex — 显示展开／折叠图标的列索引（从 0 开始）

---

导航指南

设置与入门

• 阅读： references/getting-started.md
  • NuGet 安装、_Imports.razor、Program.cs、主题／脚本设置、基本网格、IdMapping／ParentIdMapping／TreeColumnIndex、全部展开／折叠、OnActionFailure

数据绑定

• 阅读： references/data-binding.md
  • 自引用扁平数据、分层嵌套子项、远程 URL/OData/Web API、SfDataManager、按需加载
• 阅读： references/custom-binding.md
  • 重写 DataAdaptor、Read/ReadAsync、插入/更新/删除、分页与排序支持、仅支持自引用数据
• 阅读： references/graphql.md
  • Hot Chocolate 服务端、GraphQLAdaptor、GraphQLAdaptorOptions、DataManagerRequestInput、CRUD 变更、级联删除、CORS

列与单元格

• 阅读： references/columns.md
  • ColumnType、Format、TextAlign、冻结、重新排序、调整大小、列选择器、堆叠表头、列菜单、外键
• 阅读： references/cell.md
  • QueryCellInfo、CustomAttributes、ClipMode、GridLines、工具提示

排序、筛选与搜索

• 阅读： references/sorting.md
  • AllowSorting、多列排序、SortComparer、SortColumnAsync、ClearSortingAsync、保留层级结构
• 阅读： references/filtering.md
  • AllowFiltering、FilterType（FilterBar/Menu/Excel/CheckBox）、层级模式、运算符、FilterByColumnAsync。⚠️ FilterTemplate 规则请参阅 filtering.md
• 阅读： references/searching.md
  • 工具栏搜索、SearchAsync、GridSearchSettings、层级模式、高亮/清除

编辑

• 阅读： references/editing.md
  • 编辑模式（单元格/行/对话框/批量）、编辑类型、命令列、验证、模板编辑、EF Core。⚠️ ValidationRules 请参阅 editing.md。使用 <TreeGridEvents> 时，务必添加 @using Syncfusion.Blazor.Grids

行与选择

• 阅读： references/rows.md
  • RowDataBound、行/详情模板、拖放、行高、行跨越
• 阅读： references/selection.md
  • 行/单元格/两者模式、复选框列、切换、拖动选择、编程式选择、触控

分页与虚拟化

• 阅读： references/paging.md
  • AllowPaging、TreeGridPageSettings、PageSize、分页器位置/模板、编程式导航
• 阅读： references/virtualization.md
  • EnableVirtualization、EnableColumnVirtualization、与分页的区别、限制

工具栏、菜单与模板

• 阅读： references/toolbar.md
  • 内置项与自定义项、EnableToolbarItemsAsync、OnToolbarClick
• 阅读： references/context-menu.md
  • ContextMenuItems、自定义项、ContextMenuItemClicked、条件显示/隐藏
• 阅读： references/templates.md
  • 列/表头/行/详情/工具栏模板、加载指示器

导出与滚动

• 阅读： references/exporting.md
  • ExportToExcelAsync、ExportToPdfAsync、PrintAsync、自定义数据/表头、主题
• 阅读： references/scrolling.md
  • 冻结行/列（FrozenRows、IsFrozen、FreezeDirection）、AllowFreezeLineMoving、EnableStickyHeader、ScrollIntoViewAsync

高级功能

• 阅读： references/aggregates.md
  • TreeGridAggregateColumn（Field+Type 为必填项）、AggregateType、FooterTemplate、ShowChildSummary、自定义 LINQ、页面范围限制
• 阅读： references/clipboard.md
  • 复制（Ctrl+C/Ctrl+Shift+H）、CopyAsync、粘贴（Box+Batch）、CopyHierarchyMode、BeforeCopyPaste
• 阅读： references/autofill.md
  • EnableAutoFill + Cell/Box 选择 + Batch 编辑，限制
• 阅读： references/adaptive-layout.md
  • EnableAdaptiveUI、全屏对话框、垂直行模式
• 阅读： references/state-management.md
  • EnablePersistence、持久化属性、手动状态方法

事件

• 阅读： references/events.md
  • TreeGridEvents<TValue>、OnActionBegin/OnActionComplete、RowDataBound、QueryCellInfo、取消操作

---

快速入门示例

1. 安装 NuGet： Syncfusion.Blazor.TreeGrid

2. 在 _Imports.razor 中注册：

@using Syncfusion.Blazor
@using Syncfusion.Blazor.TreeGrid

3. 在 wwwroot/index.html 或 App.razor 中添加 CSS：

<link href="_content/Syncfusion.Blazor.Themes/material.css" rel="stylesheet" />

4. 添加到 Program.cs：

builder.Services.AddSyncfusionBlazor();

5. 最小组件：

@using Syncfusion.Blazor.TreeGrid

<SfTreeGrid DataSource="@TreeData" IdMapping="Id" ParentIdMapping="ParentId" TreeColumnIndex="1">
    <TreeGridColumns>
        <TreeGridColumn Field="Id" HeaderText="ID" Width="80" IsPrimaryKey="true" />
        <TreeGridColumn Field="Name" HeaderText="Name" Width="200" />
        <TreeGridColumn Field="Status" HeaderText="Status" Width="120" />
    </TreeGridColumns>
</SfTreeGrid>

@code {
    public class TaskItem
    {
        public int Id { get; set; }
        public int? ParentId { get; set; }
        public string Name { get; set; }
        public string Status { get; set; }
    }

    private List<TaskItem> TreeData = new()
    {
        new TaskItem { Id = 1, ParentId = null, Name = "Project Alpha", Status = "In Progress" },
        new TaskItem { Id = 2, ParentId = 1,    Name = "Design Phase",  Status = "Done" },
        new TaskItem { Id = 3, ParentId = 1,    Name = "Development",   Status = "In Progress" },
        new TaskItem { Id = 4, ParentId = 3,    Name = "Backend API",   Status = "Pending" },
    };
}

---

常见模式

功能齐全的 TreeGrid（排序 + 筛选 + 分页 + 编辑）

<SfTreeGrid @ref="TreeGridRef"
            DataSource="@TreeData"
            IdMapping="Id"
            ParentIdMapping="ParentId"
            TreeColumnIndex="1"
            AllowSorting="true"
            AllowFiltering="true"
            AllowPaging="true"
            Toolbar="@(new List<string> { "Add", "Edit", "Delete", "Update", "Cancel" })">
    <TreeGridEditSettings AllowAdding="true"
                          AllowEditing="true"
                          AllowDeleting="true"
                          Mode="Syncfusion.Blazor.TreeGrid.EditMode.Row" />
    <TreeGridPageSettings PageSize="10" />
    <TreeGridColumns>
        <TreeGridColumn Field="Id" IsPrimaryKey="true" Visible="false" />
        <TreeGridColumn Field="Name" HeaderText="Task" Width="220" />
        <TreeGridColumn Field="Duration" HeaderText="Days" Width="100" />
        <TreeGridColumn Field="Progress" HeaderText="%" Width="100" />
    </TreeGridColumns>
</SfTreeGrid>

@code {
    private SfTreeGrid<TaskItem> TreeGridRef;
    // ... data and model
}

Excel 和 PDF 导出

<SfTreeGrid @ref="TreeGridRef" AllowExcelExport="true" AllowPdfExport="true"
            Toolbar="@(new List<string> { "ExcelExport", "PdfExport" })">
    <TreeGridEvents TValue="TaskItem" OnToolbarClick="ToolbarClickHandler" />
    ...
</SfTreeGrid>

@code {
    private SfTreeGrid<TaskItem> TreeGridRef;

    private async Task ToolbarClickHandler(Syncfusion.Blazor.Navigations.ClickEventArgs args)
    {
        if (args.Item.Id.Contains("excelexport"))
            await TreeGridRef.ExportToExcelAsync();
        else if (args.Item.Id.Contains("pdfexport"))
            await TreeGridRef.ExportToPdfAsync();
    }
}