syncfusion-aspnetcore-tree-grid

Syncfusion ASP.NET Core TreeGrid

TreeGrid 组件以表格形式可视化自引用的层次结构数据。它支持子级/父级数据绑定（通过 childMapping 或 idMapping）、展开/折叠子行、排序、筛选、编辑、分页、导出和虚拟化。

⚠️ 安全与信任边界

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

何时使用此技能

• 在 ASP.NET Core 中呈现层次结构或父子结构数据（例如项目任务、组织结构图、物料清单）
• 对树形结构数据实现 CRUD 操作
• 对层次结构记录进行排序、筛选或搜索
• 将树形数据导出为 Excel 或 PDF
• 使用虚拟滚动或无限滚动处理大型数据集

如需完整的 API 查询，请参阅 属性与配置、事件与生命周期 和 类与枚举参考 文件。

目录

• 数据结构规则
• 文档与导航指南
• 快速入门示例
• 常见模式

数据结构规则

规则 1：层次结构数据必须使用 childMapping

严重性：🔴 严重——没有此设置，网格将无法展开/折叠

要求：

CSHTML 视图：

<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.data" childMapping="Children"
              treeColumnIndex="1" allowPaging="true">
    <e-treegrid-columns>
        <e-treegrid-column field="TaskId" headerText="Task ID" 
                           isPrimaryKey="true" textAlign="Right" width="95"></e-treegrid-column>
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
        <e-treegrid-column field="Duration" headerText="Duration" textAlign="Right" width="100"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>


<ejs-treegrid id="TreeGrid2" dataSource="@ViewBag.data">
    
</ejs-treegrid>

数据格式 C# 模型：

public class TreeGridItem
{
    public int TaskId { get; set; }
    public string TaskName { get; set; }
    public int Duration { get; set; }
    public List<TreeGridItem> Children { get; set; }  // Must match childMapping="Children"
}

// Sample data
var data = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = 1,
        TaskName = "Planning",
        Duration = 5,
        Children = new List<TreeGridItem>  // ✅ CORRECT - nested Children property
        {
            new TreeGridItem { TaskId = 2, TaskName = "Identify Site", Duration = 2 },
            new TreeGridItem { TaskId = 3, TaskName = "Perform Test",   Duration = 3 }
        }
    }
};

替代方案：使用父级 ID 的扁平结构：

<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.flatData" 
              idMapping="TaskId" parentIdMapping="ParentId" treeColumnIndex="1">
    ...
</ejs-treegrid>

var flatData = new List<TreeGridItem>
{
    new TreeGridItem { TaskId = 1, TaskName = "Planning", ParentId = null },
    new TreeGridItem { TaskId = 2, TaskName = "Identify Site", ParentId = 1 },
    new TreeGridItem { TaskId = 3, TaskName = "Perform Test",   ParentId = 1 }
};

规则 2：数据类型必须匹配

严重性：🟠 重要——类型不匹配会导致呈现/排序问题

C# 模型——正确的类型：

public class TreeGridItem
{
    public int TaskId { get; set; }              // ✅ int type
    public string TaskName { get; set; }         // ✅ string type
    public DateTime StartDate { get; set; }      // ✅ DateTime for date columns
    public decimal Price { get; set; }           // ✅ decimal for currency
}

var data = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = 1,                              // int, not string "1"
        TaskName = "Planning",
        StartDate = new DateTime(2024, 3, 15),   // DateTime, not "03/15/2024"
        Price = 1500.50m                         // decimal, not string "1500.50"
    }
};

CSHTML 列定义——匹配数据类型：

<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.data" childMapping="Children">
    <e-treegrid-columns>
        
        <e-treegrid-column field="TaskId" headerText="Task ID" 
                           type="number" textAlign="Right" width="95"></e-treegrid-column>
        
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
        
        <e-treegrid-column field="StartDate" headerText="Start Date" 
                           type="date" format="yMd" textAlign="Right" width="115"></e-treegrid-column>
        
        <e-treegrid-column field="Price" headerText="Price" 
                           type="number" format="c2" textAlign="Right" width="100"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>

❌ 错误——类型不匹配问题：

// Bad model - mixing string where types should be specific
var badData = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = "1",                // ❌ String instead of int
        StartDate = "02/03/2024"     // ❌ String instead of DateTime
    }
};
// Result: Sorting fails, formatting doesn't work, expand/collapse issues

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装 NuGet 包（Syncfusion.EJ2.AspNet.Core）
• 在 _ViewImports.cshtml 中注册 TagHelper
• 在 _Layout.cshtml 中设置 CSS/脚本 CDN
• 声明基本的 <ejs-treegrid>
• 使用 childMapping / treeColumnIndex 绑定本地数据
• 使用 <e-treegrid-columns> 定义列
• 在启动时启用分页、排序和筛选
• 使用 actionFailure 处理错误

数据绑定

📄 阅读： references/data-binding.md

• 使用 childMapping（嵌套列表）和 idMapping/parentIdMapping（扁平列表）绑定本地数据
• 通过带有 OData/WebAPI 适配器的 DataManager 绑定远程数据
• 基于 Ajax/Fetch 的绑定
• expandStateMapping——控制每行的初始展开/折叠状态
• 处理空值或缺失的父级引用

列

📄 阅读： references/columns.md

• 列 field、headerText、textAlign、width、type、format
• treeColumnIndex——指定显示展开/折叠箭头的列
• 数字/日期格式化（N2、C2、yMd、自定义）
• 锁定列、动态显示/隐藏列
• 复选框列（showCheckbox、autoCheckHierarchy）
• 使用 valueAccessor 创建计算/表达式列
• 列菜单（showColumnMenu）
• 列重排、调整大小、自动适配
• 列模板、列跨行、表头、复杂数据绑定

排序

📄 阅读： references/sorting.md

• 使用 allowSorting 启用
• 使用 e-treegrid-sortsettings 设置初始排序
• 多列排序（CTRL + 单击）
• 禁用单列排序（在列上设置 allowSorting: false）
• 排序事件（actionBegin、actionComplete）
• 通过 sortColumn / clearSorting 以编程方式排序/清除排序

筛选

📄 阅读： references/filtering.md

• 使用 allowFiltering 启用
• 筛选类型：FilterBar（默认）、Menu、Excel-like
• 筛选层级模式：Parent、Child、Both、None
• 使用谓词设置初始筛选
• 筛选运算符（startswith、contains、equal、greaterthan 等）
• 禁用单列筛选

编辑

📄 阅读： references/editing.md

• 使用 e-treegrid-editSettings 和 isPrimaryKey 启用
• 编辑模式：Cell、Row、Dialog、Batch
• 工具栏支持 Add/Edit/Delete/Update/Cancel
• newRowPosition：Top、Bottom、Above、Below、Child
• 删除确认对话框
• 添加时设置默认列值
• 禁用单列编辑
• 验证规则
• 将编辑后的数据持久化到服务器

分页

📄 阅读： references/paging.md

• 使用 allowPaging 启用
• e-treegrid-pagesettings：pageSize、pageSizeMode（All/Root）
• 页面大小下拉列表、分页器模板
• 通过 dataBound 事件在顶部呈现分页器

选择

📄 阅读： references/selection.md

• 行、单元格、行与单元格两种选择模式
• 单选或多选类型（e-treegrid-selectionsettings）
• 使用 checkboxMode 进行复选框选择
• 通过编程方式选择

聚合

📄 阅读： references/aggregates.md

• 内置类型：Sum、Average、Min、Max、Count、Truecount、Falsecount
• 页脚聚合和子级聚合（父行页脚）
• 使用 showChildSummary 显示子级聚合
• 自定义聚合函数
• 使用 footerTemplate 自定义显示内容

行自定义

📄 阅读： references/row.md

• 使用 rowDataBound 设置条件样式
• 交替行样式（.e-altrow）
• 行模板、详情模板
• 行拖放（allowRowDragAndDrop）
• 行高、行合并

单元格自定义

📄 阅读： references/cell.md

• 使用 queryCellInfo 自定义单元格
• 单元格自定义属性
• 自动换行（allowTextWrap）
• 裁剪模式（Clip、Ellipsis、EllipsisWithTooltip）
• 网格线

导出（Excel）

📄 阅读： references/excel-export.md

• Excel 导出（allowExcelExport、excelExport()）
• 在导出时保留折叠状态
• 导出自定义聚合
• 标题/页脚、单元格样式自定义
• 服务端导出选项

PDF 导出

📄 阅读： references/pdf-export.md

• PDF 导出（allowPdfExport、pdfExport()）
• PDF 导出选项和配置
• 页面方向（Portrait、Landscape）
• 自定义标题、页脚和样式
• PDF 单元格样式自定义
• 服务端 PDF 导出

打印

📄 阅读： references/print.md

• 使用 allowPrinting 启用打印
• 通过工具栏按钮或外部按钮打印
• 仅打印当前页（printMode: 'CurrentPage'）
• 打印时显示/隐藏列
• 处理大型数据集
• 页面设置配置

剪贴板

📄 阅读： references/clipboard.md

• 使用 Ctrl+C 和 Ctrl+Shift+H 复制到剪贴板
• 使用外部按钮复制
• 复制层级模式（Parent、Child、Both、None）
• 使用拖动填充的自动填充功能
• 使用 Ctrl+V 粘贴
• 类型转换限制

滚动

📄 阅读： references/scrolling.md

• 基本滚动和响应式配置
• 粘性标题、行/列虚拟化和无限滚动
• 针对大型数据集的性能优化

自适应布局

📄 阅读： references/adaptive.md

• 使用 enableAdaptiveUI 为移动设备和平板设备提供响应式 UI
• 在小屏幕上使用自适应对话框模式进行筛选和编辑
• 优化展开/折叠行为，适配触控操作
• 将列选择器适配为移动端对话框
• 使用垂直行呈现模式，提升移动端可读性
• TreeGrid 响应式设计最佳实践

冻结行和列

📄 阅读： references/frozen.md

• 使用 frozenRows、frozenColumns 或 isFrozen 属性冻结行和列
• 通过左侧／右侧定位控制冻结方向
• 与其他功能配合使用时的限制和兼容性注意事项

样式和外观

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

• 使用 CSS 类自定义 Tree Grid 所有元素的样式
• 标题、行、单元格、选择项和汇总行的 CSS 覆盖示例
• 使用 Syncfusion Theme Studio 自定义主题选项

不可变模式

📄 阅读： references/immutable.md

• 使用 enableImmutableMode="true" 启用
• 针对大型数据集的性能优化
• 比较数据时需要主键
• 仅重新渲染已修改的行
• 批量操作的性能优势
• 限制和解决方法

工具栏

📄 阅读： references/toolbar.md

• 内置工具栏项（Add、Edit、Delete、Update、Cancel、Search、ExcelExport、PdfExport 等）
• 支持自定义文本、图标、工具提示和对齐方式的工具栏项
• 带事件参数的工具栏点击处理程序
• 内置项的 ID 模式和识别方式
• 根据行选择动态禁用工具栏项
• 工具栏设计和布局最佳实践
• 与工具栏按钮集成的编辑模式

上下文菜单

📄 阅读： references/context-menu.md

• 用于数据操作和列操作的默认上下文菜单项
• 具有层级感知功能的自定义上下文菜单项
• 使用目标选择器（.e-content、.e-headercell）控制上下文可见性
• 包含行和列信息的上下文菜单点击处理程序
• 根据行状态（父级／子级）动态启用或禁用菜单项
• TreeGrid 的层级感知展开／折叠菜单
• 高级场景：仅限父级的操作、条件菜单项
• TreeGrid 专用上下文菜单设计最佳实践

搜索

📄 阅读： references/searching.md

• 启用对 TreeGrid 层级数据的全文搜索
• 添加搜索工具栏项，以便在用户输入时实时筛选
• 配置搜索字段范围（所有列或特定列子集）
• 使用运算符搜索（contains、startsWith、endsWith、equal、notEqual）
• 从外部输入控件以编程方式触发搜索
• 在层级结构中搜索，并在匹配子项时自动展开父行
• 清除搜索并重置，以显示所有行
• 处理搜索事件（actionBegin、actionComplete）以实现自定义逻辑
• 搜索大型层级数据集的最佳实践

加载动画

📄 阅读： references/loading-animation.md

• 加载指示器类型：Spinner（默认）和 Shimmer 动画
• 加载动画的显示时机（初始渲染、排序、筛选、分页、搜索）
• 通过 DataManager 绑定远程数据并显示加载动画
• 以编程方式控制加载指示器（显示／隐藏）
• 使用操作事件自定义加载行为
• 加载状态下的用户体验最佳实践
• 移动设备和慢速网络优化

全球化与本地化

📄 阅读： references/global-local.md

• 通过 locale 属性进行特定区域的数字和日期格式设置
• 本地化 UI 字符串（工具栏、对话框、分页器、筛选器、展开／折叠文本）
• 支持阿拉伯语、希伯来语和其他 RTL 语言的从右向左（RTL）布局
• 加载 CLDR 数据并配置区域设置
• 用于货币、日期和数字列的格式代码（C2、yMd、N2）
• 支持多区域设置并动态切换语言
• 全球化应用的最佳实践

状态管理

📄 阅读： references/state-management.md

• 使用 enablePersistence 跨会话持久保存 TreeGrid 状态
• 保存和恢复排序、筛选、分页及列首选项
• 页面重新加载时保留父行的展开/折叠状态
• 基于 LocalStorage 的自动持久化和手动状态检索
• 以编程方式将 TreeGrid 状态重置为默认值
• 针对敏感数据的自定义服务器端状态持久化
• 层次结构数据状态管理的最佳实践

无障碍

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 标准
• 键盘导航
• ARIA 属性
• 屏幕阅读器支持

属性与配置

📄 阅读： references/properties-configuration.md

• 按用途分类查阅 145+ 个 TreeGrid 属性
• 数据配置（dataSource、childMapping、idMapping、parentIdMapping、expandStateMapping）
• UI 布局（height、width、rowHeight、treeColumnIndex）
• 网格外观（gridLines、enableAltRow、enableRtl、enableHover、clipMode）
• 功能开关表（分页、排序、筛选、编辑、选择等）
• 性能调优（虚拟化、无限滚动、不可变模式、持久化）
• 事件回调和处理程序
• 高级配置对象（EditSettings、PageSettings、FilterSettings、SelectionSettings 等）

事件与生命周期

📄 阅读： references/events-methods.md

• 生命周期事件（created、load、dataBound、beforeDataBound、dataSourceChanged）
• 操作事件（actionBegin、actionComplete、actionFailure）
• 展开/折叠事件（expanding、expanded、collapsing、collapsed）
• 编辑事件（beginEdit、cellEdit、cellSave、cellSaved、batchAdd、batchDelete、beforeBatchSave）
• 选择事件（rowSelected、rowSelecting、rowDeselected、checkboxChange）
• 拖放事件（rowDragStart、rowDrop、columnDragStart、columnDrop）
• 自定义渲染事件（queryCellInfo、rowDataBound、detailDataBound）
• 导出事件（beforeExcelExport、excelExportComplete、beforePdfExport、pdfQueryCellInfo）
• 每个类别的完整事件签名和示例

设置类与枚举参考

📄 阅读： references/classes-enums-reference.md

• 枚举：CopyHierarchyType、EditMode、FilterHierarchyMode、FilterType、PageSizeMode、RowPosition、WrapMode
• 设置类：EditSettings、PageSettings、SortSettings、FilterSettings、SelectionSettings、RowDropSettings、InfiniteScrollSettings
• 列配置：TreeGridColumn、StackedHeaderCell 类
• 用于流畅 API 的构建器模式和标签帮助程序方法
• 各设置类的完整属性定义

快速入门示例

包含本地数据、列、排序、筛选和分页的最简 TreeGrid：

_ViewImports.cshtml

@addTagHelper *, Syncfusion.EJ2

_Layout.cshtml（位于 <head> 中）

<link rel="stylesheet" href="~/ej2/ej2version/fluent2.css" />

<script src="~/ej2/ej2version/dist/ej2.min.js"></script>

_Layout.cshtml（位于 <body> 末尾）

<ejs-scripts></ejs-scripts>

Index.cshtml

@{
    var data = TreeGridItems.GetTreeData();
}

<ejs-treegrid id="TreeGrid" dataSource="@data" childMapping="Children"
              treeColumnIndex="1" allowSorting="true" allowFiltering="true" allowPaging="true">
    <e-treegrid-pagesettings pageSize="5"></e-treegrid-pagesettings>
    <e-treegrid-columns>
        <e-treegrid-column field="TaskId" headerText="Task ID" isPrimaryKey="true"
                           textAlign="Right" width="95"></e-treegrid-column>
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
        <e-treegrid-column field="StartDate" headerText="Start Date"
                           textAlign="Right" format="yMd" type="date" width="115"></e-treegrid-column>
        <e-treegrid-column field="Duration" headerText="Duration"
                           textAlign="Right" width="100"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>

Index.cshtml.cs（或 Controller）

public class TreeGridItems
{
    public int TaskId { get; set; }
    public string TaskName { get; set; }
    public DateTime StartDate { get; set; }
    public int Duration { get; set; }
    public List<TreeGridItems> Children { get; set; }

    public static List<TreeGridItems> GetTreeData()
    {
        return new List<TreeGridItems>
        {
            new TreeGridItems
            {
                TaskId = 1, TaskName = "Planning",
                StartDate = new DateTime(2021, 6, 7), Duration = 5,
                Children = new List<TreeGridItems>
                {
                    new TreeGridItems { TaskId = 2, TaskName = "Plan timeline", StartDate = new DateTime(2021, 6, 7), Duration = 5 },
                    new TreeGridItems { TaskId = 3, TaskName = "Plan budget",   StartDate = new DateTime(2021, 6, 7), Duration = 5 }
                }
            }
        };
    }
}

常见模式

何时使用 childMapping，何时使用 idMapping

• childMapping：数据为嵌套结构（每个父项都有一个 Children 列表）→ 绑定 childMapping="Children"
• idMapping + parentIdMapping：数据为扁平结构，并通过父 ID 引用父项 → 绑定 idMapping="TaskId" parentIdMapping="ParentId"

使用工具栏启用编辑

<ejs-treegrid id="TreeGrid" dataSource="@data" childMapping="Children"
              treeColumnIndex="1" toolbar="@(new List<string>() {"Add","Edit","Delete","Update","Cancel"})">
    <e-treegrid-editsettings allowAdding="true" allowEditing="true"
                             allowDeleting="true" mode="Row"></e-treegrid-editsettings>
    <e-treegrid-columns>
        <e-treegrid-column field="TaskId" headerText="Task ID"
                           isPrimaryKey="true" width="90"></e-treegrid-column>
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>

务必在一列上设置 isPrimaryKey="true"——编辑和删除操作都需要此设置。

避免常见错误

• 请勿同时启用分页和虚拟化
• 请勿同时设置 isFrozen 和 frozenColumns
• showCheckbox 列只能定义在树列上
• textAlign="Right" 不适用于树列
• 请勿同时启用 idMapping 和 childMapping