syncfusion-aspnetcore-tree-grid

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion ASP.NET Core TreeGrid

The TreeGrid component visualizes self-referential hierarchical data in a tabular format. It supports child/parent data binding (via

childMapping

idMapping

), expand/collapse of child rows, sorting, filtering, editing, paging, export, and virtualization.

TreeGrid组件以表格形式可视化自引用的分层数据。它支持子/父数据绑定（通过

childMapping

或

idMapping

）、子行展开/折叠、排序、筛选、编辑、分页、导出和虚拟化。

⚠️ Security & Trust Boundary

⚠️ 安全与信任边界

The TreeGrid skill does not perform any remote data access.
All external API interaction is handled by a separate DataManager skill outside this skill’s trust boundary.

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

When to Use This Skill

何时使用此技能

Rendering hierarchical or parent-child structured data in ASP.NET Core (e.g. project tasks, org charts, bill of materials)
Implementing CRUD operations on tree-structured data
Sorting, filtering, or searching across hierarchical records
Exporting tree data to Excel or PDF
Handling large datasets with virtual scrolling or infinite scroll

Refer to Properties & Configuration, Events & Lifecycle, and Classes & Enums Reference files for complete API lookup.

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

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

Data Structure Rules

数据结构规则

Rule 1: childMapping is MANDATORY for Hierarchical Data

规则1：分层数据必须设置childMapping

Severity: 🔴 CRITICAL - Grid will not expand/collapse without this

Requirement:

CSHTML View:

cshtml

<!-- ✅ REQUIRED - childMapping matches data property name exactly -->
<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>

<!-- ❌ WRONG - No childMapping = No expansion possible -->
<ejs-treegrid id="TreeGrid2" dataSource="@ViewBag.data">
    <!-- Missing childMapping & treeColumnIndex - Won't expand! -->
</ejs-treegrid>

Data Format C# Model:

csharp

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

Alternative: Flat Structure with Parent IDs:

cshtml

<!-- Use idMapping + parentIdMapping instead of childMapping -->
<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.flatData" 
              idMapping="TaskId" parentIdMapping="ParentId" treeColumnIndex="1">
    ...
</ejs-treegrid>

csharp

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

严重性：🔴 关键 - 不设置此项，网格无法展开/折叠

要求:

CSHTML视图:

cshtml

<!-- ✅ 必填项 - childMapping必须与数据属性名完全匹配 -->
<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>

<!-- ❌ 错误示例 - 无childMapping则无法展开 -->
<ejs-treegrid id="TreeGrid2" dataSource="@ViewBag.data">
    <!-- 缺少childMapping和treeColumnIndex - 无法展开！ -->
</ejs-treegrid>

C#模型数据格式:

csharp

public class TreeGridItem
{
    public int TaskId { get; set; }
    public string TaskName { get; set; }
    public int Duration { get; set; }
    public List<TreeGridItem> Children { get; set; }  // 必须与childMapping="Children"匹配
}

// 示例数据
var data = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = 1,
        TaskName = "Planning",
        Duration = 5,
        Children = new List<TreeGridItem>  // ✅ 正确 - 嵌套的Children属性
        {
            new TreeGridItem { TaskId = 2, TaskName = "Identify Site", Duration = 2 },
            new TreeGridItem { TaskId = 3, TaskName = "Perform Test",   Duration = 3 }
        }
    }
};

替代方案：带父ID的扁平结构:

cshtml

<!-- 使用idMapping + parentIdMapping替代childMapping -->
<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.flatData" 
              idMapping="TaskId" parentIdMapping="ParentId" treeColumnIndex="1">
    ...
</ejs-treegrid>

csharp

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

Rule 2: Data Type Matching is MANDATORY

规则2：数据类型匹配是必填项

Severity: 🟠 IMPORTANT - Type mismatches cause rendering/sorting issues

C# Model - Correct Types:

csharp

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 Column Definition - Match Data Types:

cshtml

<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.data" childMapping="Children">
    <e-treegrid-columns>
        <!-- field "TaskId" is int, so type="number" -->
        <e-treegrid-column field="TaskId" headerText="Task ID" 
                           type="number" textAlign="Right" width="95"></e-treegrid-column>
        <!-- field "TaskName" is string, type="string" (default) -->
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
        <!-- field "StartDate" is DateTime, so type="date" with format -->
        <e-treegrid-column field="StartDate" headerText="Start Date" 
                           type="date" format="yMd" textAlign="Right" width="115"></e-treegrid-column>
        <!-- field "Price" is decimal, type="number" with currency format -->
        <e-treegrid-column field="Price" headerText="Price" 
                           type="number" format="c2" textAlign="Right" width="100"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>

❌ WRONG - Type Mismatch Issues:

csharp

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

严重性：🟠 重要 - 类型不匹配会导致渲染/排序问题

C#模型 - 正确类型:

csharp

public class TreeGridItem
{
    public int TaskId { get; set; }              // ✅ int类型
    public string TaskName { get; set; }         // ✅ string类型
    public DateTime StartDate { get; set; }      // ✅ DateTime用于日期列
    public decimal Price { get; set; }           // ✅ decimal用于货币
}

var data = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = 1,                              // int类型，而非字符串"1"
        TaskName = "Planning",
        StartDate = new DateTime(2024, 3, 15),   // DateTime类型，而非字符串"03/15/2024"
        Price = 1500.50m                         // decimal类型，而非字符串"1500.50"
    }
};

CSHTML列定义 - 匹配数据类型:

cshtml

<ejs-treegrid id="TreeGrid" dataSource="@ViewBag.data" childMapping="Children">
    <e-treegrid-columns>
        <!-- 字段"TaskId"是int类型，所以type="number" -->
        <e-treegrid-column field="TaskId" headerText="Task ID" 
                           type="number" textAlign="Right" width="95"></e-treegrid-column>
        <!-- 字段"TaskName"是string类型，type="string"（默认值） -->
        <e-treegrid-column field="TaskName" headerText="Task Name" width="220"></e-treegrid-column>
        <!-- 字段"StartDate"是DateTime类型，所以type="date"并设置格式 -->
        <e-treegrid-column field="StartDate" headerText="Start Date" 
                           type="date" format="yMd" textAlign="Right" width="115"></e-treegrid-column>
        <!-- 字段"Price"是decimal类型，type="number"并设置货币格式 -->
        <e-treegrid-column field="Price" headerText="Price" 
                           type="number" format="c2" textAlign="Right" width="100"></e-treegrid-column>
    </e-treegrid-columns>
</ejs-treegrid>

❌ 错误示例 - 类型不匹配问题:

csharp

// 错误模型 - 在应使用特定类型的地方混用字符串
var badData = new List<TreeGridItem>
{
    new TreeGridItem
    {
        TaskId = "1",                // ❌ 字符串而非int
        StartDate = "02/03/2024"     // ❌ 字符串而非DateTime
    }
};
// 结果：排序失败、格式化无效、展开/折叠异常

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

NuGet installation (
```
Syncfusion.EJ2.AspNet.Core
```
)
TagHelper registration in
```
_ViewImports.cshtml
```
CSS/script CDN setup in
```
_Layout.cshtml
```
Basic
```
<ejs-treegrid>
```
declaration
Binding local data with
```
childMapping
```
/
```
treeColumnIndex
```
Defining columns with
```
<e-treegrid-columns>
```
Enabling paging, sorting, and filtering at startup
Error handling with
```
actionFailure
```

📄 阅读: references/getting-started.md

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

Data Binding

数据绑定

📄 Read: references/data-binding.md

Local data with
```
childMapping
```
(nested list) and
```
idMapping
```
/
```
parentIdMapping
```
(flat list)
Remote data via
```
DataManager
```
with OData/WebAPI adaptor
Ajax/Fetch-based binding
```
expandStateMapping
```
— control initial expand/collapse state per row
Handling null or missing parent references

📄 阅读: references/data-binding.md

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

Columns

列配置

📄 Read: references/columns.md

Column
```
field
```
,
```
headerText
```
,
```
textAlign
```
,
```
width
```
,
```
type
```
,
```
format
```
```
treeColumnIndex
```
— which column shows expand/collapse arrows
Number/date formatting (N2, C2, yMd, custom)
Lock columns, show/hide columns dynamically
Checkbox column (
```
showCheckbox
```
,
```
autoCheckHierarchy
```
)
```
valueAccessor
```
for computed/expression columns
Column menu (
```
showColumnMenu
```
)
Column reorder, resize, auto-fit
Column templates, column spanning, headers, complex data binding

📄 阅读: references/columns.md

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

Sorting

排序

📄 Read: references/sorting.md

Enable with
```
allowSorting
```
Initial sort via
```
e-treegrid-sortsettings
```
Multi-column sort (CTRL + click)
Disable sort per column (
```
allowSorting: false
```
on column)
Sort events (
```
actionBegin
```
,
```
actionComplete
```
)
Programmatic sort/clear via
```
sortColumn
```
/
```
clearSorting
```

📄 阅读: references/sorting.md

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

Filtering

筛选

📄 Read: references/filtering.md

Enable with
```
allowFiltering
```
Filter types: FilterBar (default), Menu, Excel-like
Filter hierarchy modes: Parent, Child, Both, None
Initial filter with predicate
Filter operators (startswith, contains, equal, greaterthan, etc.)
Disable filter per column

📄 阅读: references/filtering.md

通过
```
allowFiltering
```
启用筛选
筛选类型：筛选栏（默认）、菜单、类Excel筛选
筛选层级模式：父级、子级、两者、无
使用谓词设置初始筛选
筛选操作符（startswith、contains、equal、greaterthan等）
按列禁用筛选

Editing

编辑

📄 Read: references/editing.md

Enable with
```
e-treegrid-editSettings
```
and
```
isPrimaryKey
```
Edit modes: Cell, Row, Dialog, Batch
Toolbar with Add/Edit/Delete/Update/Cancel
```
newRowPosition
```
: Top, Bottom, Above, Below, Child
Delete confirmation dialog
Default column values on add
Disable editing per column
Validation rules
Persisting edited data to server

📄 阅读: references/editing.md

通过
```
e-treegrid-editSettings
```
和
```
isPrimaryKey
```
启用编辑
编辑模式：单元格、行、对话框、批量
工具栏包含添加/编辑/删除/更新/取消按钮
```
newRowPosition
```
: 顶部、底部、上方、下方、子级
删除确认对话框
添加时设置列默认值
按列禁用编辑
验证规则
将编辑后的数据持久化到服务器

Paging

分页

📄 Read: references/paging.md

Enable with
```
allowPaging
```

e-treegrid-pagesettings

pageSize

pageSizeMode

(All/Root)

Page size dropdown, pager template
Render pager at top via
```
dataBound
```
event

📄 阅读: references/paging.md

通过
```
allowPaging
```
启用分页

e-treegrid-pagesettings

pageSize

、

pageSizeMode

（全部/根节点）

分页大小下拉框、分页器模板
通过
```
dataBound
```
事件在顶部渲染分页器

Selection

选择

📄 Read: references/selection.md

Row, Cell, Both selection modes
Single vs Multiple type (
```
e-treegrid-selectionsettings
```
)
Checkbox selection with
```
checkboxMode
```
Programmatic selection

📄 阅读: references/selection.md

行、单元格、两者选择模式
单选 vs 多选（
```
e-treegrid-selectionsettings
```
）
复选框选择配合
```
checkboxMode
```
编程式选择

Aggregates

聚合

📄 Read: references/aggregates.md

Built-in types: Sum, Average, Min, Max, Count, Truecount, Falsecount
Footer aggregate and child (parent row footer) aggregate
```
showChildSummary
```
to show child aggregate
Custom aggregate function
```
footerTemplate
```
for custom display

📄 阅读: references/aggregates.md

内置类型：求和、平均值、最小值、最大值、计数、真计数、假计数
页脚聚合和子级（父行页脚）聚合
```
showChildSummary
```
用于显示子级聚合
自定义聚合函数
```
footerTemplate
```
用于自定义显示

Row Customization

行自定义

📄 Read: references/row.md

```
rowDataBound
```
for conditional styling
Alternate row styling (
```
.e-altrow
```
)
Row template, detail template
Row drag-and-drop (
```
allowRowDragAndDrop
```
)
Row height, row spanning

📄 阅读: references/row.md

```
rowDataBound
```
用于条件样式
交替行样式（
```
.e-altrow
```
）
行模板、详情模板
行拖拽（
```
allowRowDragAndDrop
```
）
行高、行合并

Cell Customization

单元格自定义

📄 Read: references/cell.md

```
queryCellInfo
```
for per-cell customization
Custom attributes on cells
Auto text wrap (
```
allowTextWrap
```
)
Clip mode (Clip, Ellipsis, EllipsisWithTooltip)
Grid lines

📄 阅读: references/cell.md

```
queryCellInfo
```
用于逐单元格自定义
单元格自定义属性
自动文本换行（
```
allowTextWrap
```
）
裁剪模式（Clip、Ellipsis、EllipsisWithTooltip）
网格线

Export (Excel)

导出（Excel）

📄 Read: references/excel-export.md

Excel export (
```
allowExcelExport
```
,
```
excelExport()
```
)
Persist collapsed state in export
Custom aggregates in export
Headers/footers, cell style customization
Server-side export options

📄 阅读: references/excel-export.md

Excel导出（
```
allowExcelExport
```
、
```
excelExport()
```
）
在导出中保留折叠状态
导出中的自定义聚合
表头/页脚、单元格样式自定义
服务器端导出选项

PDF Export

PDF导出

📄 Read: references/pdf-export.md

PDF export (
```
allowPdfExport
```
,
```
pdfExport()
```
)
PDF export options and configurations
Page orientation (Portrait, Landscape)
Custom headers, footers, and styling
Cell style customization for PDF
Server-side PDF export

📄 阅读: references/pdf-export.md

PDF导出（
```
allowPdfExport
```
、
```
pdfExport()
```
）
PDF导出选项和配置
页面方向（纵向、横向）
自定义表头、页脚和样式
PDF单元格样式自定义
服务器端PDF导出

Print

打印

📄 Read: references/print.md

Enable printing with
```
allowPrinting
```
Print via toolbar button or external button
Print current page only (
```
printMode: 'CurrentPage'
```
)
Show/hide columns during print
Handling large datasets
Page setup configuration

📄 阅读: references/print.md

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

Clipboard

剪贴板

📄 Read: references/clipboard.md

Copy to clipboard with Ctrl+C and Ctrl+Shift+H
Copy with external buttons
Copy hierarchy modes (Parent, Child, Both, None)
AutoFill feature with drag-to-fill
Paste functionality with Ctrl+V
Type conversion limitations

📄 阅读: references/clipboard.md

使用Ctrl+C和Ctrl+Shift+H复制到剪贴板
通过外部按钮复制
复制层级模式（父级、子级、两者、无）
拖拽填充的自动填充功能
使用Ctrl+V粘贴功能
类型转换限制

Scrolling

滚动

📄 Read: references/scrolling.md

Basic scrolling and responsive configurations
Sticky header, row/column virtualization, and infinite scrolling
Performance optimization for large datasets

📄 阅读: references/scrolling.md

基础滚动和响应式配置
固定表头、行/列虚拟化、无限滚动
大型数据集的性能优化

Adaptive Layout

自适应布局

📄 Read: references/adaptive.md

Responsive UI with
```
enableAdaptiveUI
```
for mobile and tablet devices
Adaptive dialog mode for filtering and editing on small screens
Expand/collapse behavior optimization for touch interaction
Column chooser adaptation to mobile dialogs
Vertical row rendering mode for enhanced mobile readability
Best practices for responsive TreeGrid design

📄 阅读: references/adaptive.md

通过
```
enableAdaptiveUI
```
为移动和平板设备提供响应式UI
在小屏幕上为筛选和编辑提供自适应对话框模式
针对触摸交互优化展开/折叠行为
列选择器适配移动端对话框
垂直行渲染模式提升移动端可读性
响应式TreeGrid设计的最佳实践

Frozen Rows and Columns

冻结行和列

📄 Read: references/frozen.md

Freeze rows and columns using
```
frozenRows
```
,
```
frozenColumns
```
, or
```
isFrozen
```
property
Freeze direction control with Left/Right positioning
Limitations and compatibility considerations with other features

📄 阅读: references/frozen.md

使用
```
frozenRows
```
、
```
frozenColumns
```
或
```
isFrozen
```
属性冻结行和列
通过左/右定位控制冻结方向
与其他功能的限制和兼容性考虑

Styling and Appearance

样式与外观

📄 Read: references/styling-and-appearance.md

Customize Tree Grid styling with CSS classes for all elements
CSS override examples for headers, rows, cells, selection, and summary
Custom theme options using Syncfusion Theme Studio

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

使用CSS类自定义TreeGrid所有元素的样式
表头、行、单元格、选择、摘要的CSS覆盖示例
使用Syncfusion主题工作室自定义主题选项

Immutable Mode

不可变模式

📄 Read: references/immutable.md

Enable with
```
enableImmutableMode="true"
```
Performance optimization for large datasets
Primary key requirement for comparison
Selective re-render of modified rows
Performance benefits for batch operations
Limitations and workarounds

📄 阅读: references/immutable.md

通过
```
enableImmutableMode="true"
```
启用
大型数据集的性能优化
比较所需的主键要求
选择性重新渲染修改后的行
批量操作的性能优势
限制和解决方法

Toolbar

工具栏

📄 Read: references/toolbar.md

Built-in toolbar items (Add, Edit, Delete, Update, Cancel, Search, ExcelExport, PdfExport, etc.)
Custom toolbar items with text, icons, tooltips, and alignment
Toolbar click handler with event arguments
Built-in item ID patterns and identification
Disabling toolbar items dynamically based on row selection
Best practices for toolbar design and layout
Edit mode integration with toolbar buttons

📄 阅读: references/toolbar.md

内置工具栏项（添加、编辑、删除、更新、取消、搜索、Excel导出、PDF导出等）
带文本、图标、工具提示和对齐方式的自定义工具栏项
带事件参数的工具栏点击处理器
内置项ID模式和识别
根据行选择动态禁用工具栏项
工具栏设计和布局的最佳实践
编辑模式与工具栏按钮的集成

Context Menu

上下文菜单

📄 Read: references/context-menu.md

Default context menu items for data manipulation and column operations
Custom context menu items with hierarchy-aware functionality
Contextual visibility using target selectors (.e-content, .e-headercell)
Context menu click handler with row and column information
Enable/disable items dynamically based on row state (parent/child)
Hierarchy-aware expand/collapse menus for TreeGrid
Advanced scenarios: parent-only operations, conditional menu items
Best practices for TreeGrid-specific context menu design

📄 阅读: references/context-menu.md

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

Searching

搜索

📄 Read: references/searching.md

Enable full-text search across TreeGrid hierarchical data
Add search toolbar item for real-time filtering as user types
Configure search field scope (all columns or specific column subset)
Search with operators (contains, startsWith, endsWith, equal, notEqual)
Programmatic search triggering from external input controls
Search in hierarchy with automatic parent row expansion on child matches
Clear search and reset to show all rows
Handle search events (actionBegin, actionComplete) for custom logic
Best practices for searching large hierarchical datasets

📄 阅读: references/searching.md

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

Loading Animation

加载动画

📄 Read: references/loading-animation.md

Loading indicator types: Spinner (default) and Shimmer animations
When loading animation displays (initial render, sorting, filtering, paging, searching)
Remote data binding with loading animation via DataManager
Programmatic control of loading indicator (show/hide)
Customizing loading behavior with action events
Best practices for UX with loading states
Mobile and slow network optimization

📄 阅读: references/loading-animation.md

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

Globalization & Localization

全球化与本地化

📄 Read: references/global-local.md

Culture-specific number and date formatting via
```
locale
```
property
Localization of UI strings (toolbar, dialogs, pager, filter, expand/collapse text)
Right-to-left (RTL) layout support for Arabic, Hebrew, and other RTL languages
CLDR data loading and culture configuration
Format codes (C2, yMd, N2) for currency, date, and number columns
Multi-locale support with dynamic language switching
Best practices for global applications

📄 阅读: references/global-local.md

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

State Management

状态管理

📄 Read: references/state-management.md

Persist TreeGrid state across sessions with
```
enablePersistence
```
Save and restore sorting, filtering, paging, and column preferences
Preserve expand/collapse state of parent rows on page reload
LocalStorage-based automatic persistence and manual state retrieval
Reset TreeGrid state to defaults programmatically
Custom server-side state persistence for sensitive data
Best practices for state management in hierarchical data

📄 阅读: references/state-management.md

通过
```
enablePersistence
```
在会话间持久化TreeGrid状态
保存和恢复排序、筛选、分页和列偏好设置
在页面重新加载时保留父行的展开/折叠状态
基于LocalStorage的自动持久化和手动状态检索
以编程方式将TreeGrid状态重置为默认值
敏感数据的自定义服务器端状态持久化
分层数据状态管理的最佳实践

Accessibility

可访问性

📄 Read: references/accessibility.md

WCAG 2.1 compliance
Keyboard navigation
ARIA attributes
Screen reader support

📄 阅读: references/accessibility.md

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

Properties & Configuration

属性与配置

📄 Read: references/properties-configuration.md

Lookup 145+ TreeGrid properties organized by concern
Data configuration (dataSource, childMapping, idMapping, parentIdMapping, expandStateMapping)
UI layout (height, width, rowHeight, treeColumnIndex)
Grid appearance (gridLines, enableAltRow, enableRtl, enableHover, clipMode)
Feature toggles table (Paging, Sorting, Filtering, Editing, Selection, etc.)
Performance tuning (virtualization, infinite scroll, immutable mode, persistence)
Event callbacks and handlers
Advanced configuration objects (EditSettings, PageSettings, FilterSettings, SelectionSettings, etc.)

📄 阅读: 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等）

Events & Lifecycle

事件与生命周期

📄 Read: references/events-methods.md

Lifecycle events (created, load, dataBound, beforeDataBound, dataSourceChanged)
Action events (actionBegin, actionComplete, actionFailure)
Expand/collapse events (expanding, expanded, collapsing, collapsed)
Edit events (beginEdit, cellEdit, cellSave, cellSaved, batchAdd, batchDelete, beforeBatchSave)
Selection events (rowSelected, rowSelecting, rowDeselected, checkboxChange)
Drag & drop events (rowDragStart, rowDrop, columnDragStart, columnDrop)
Custom rendering events (queryCellInfo, rowDataBound, detailDataBound)
Export events (beforeExcelExport, excelExportComplete, beforePdfExport, pdfQueryCellInfo)
Complete event signatures and examples for each category

📄 阅读: 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）
每个类别的完整事件签名和示例

Settings Classes & Enums Reference

设置类与枚举参考

📄 Read: references/classes-enums-reference.md

Enums: CopyHierarchyType, EditMode, FilterHierarchyMode, FilterType, PageSizeMode, RowPosition, WrapMode
Settings classes: EditSettings, PageSettings, SortSettings, FilterSettings, SelectionSettings, RowDropSettings, InfiniteScrollSettings
Column configuration: TreeGridColumn, StackedHeaderCell classes
Builder pattern for fluent API and tag helper approach
Complete property definitions for each settings class

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

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

Quick Start Example

快速入门示例

Minimal TreeGrid with local data, columns, sorting, filtering, and paging:

_ViewImports.cshtml

cshtml

@addTagHelper *, Syncfusion.EJ2

_Layout.cshtml
(inside

<head>

)

cshtml

<!-- Syncfusion ASP.NET Core controls styles -->
<link rel="stylesheet" href="~/ej2/ej2version/fluent2.css" />
<!-- Syncfusion ASP.NET Core controls scripts -->
<script src="~/ej2/ej2version/dist/ej2.min.js"></script>

_Layout.cshtml
(end of

<body>

)

cshtml

<ejs-scripts></ejs-scripts>

Index.cshtml

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
(or Controller)

csharp

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

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

_ViewImports.cshtml

cshtml

@addTagHelper *, Syncfusion.EJ2

_Layout.cshtml
（

<head>

内）

cshtml

<!-- Syncfusion ASP.NET Core控件样式 -->
<link rel="stylesheet" href="~/ej2/ej2version/fluent2.css" />
<!-- Syncfusion ASP.NET Core控件脚本 -->
<script src="~/ej2/ej2version/dist/ej2.min.js"></script>

_Layout.cshtml
（

<body>

末尾）

cshtml

<ejs-scripts></ejs-scripts>

Index.cshtml

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
（或控制器）

csharp

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

Common Patterns

常见模式

When to use

childMapping

idMapping

何时使用

childMapping

idMapping

childMapping
: Data is nested (each parent has a
```
Children
```
list) → bind
```
childMapping="Children"
```

idMapping
+
parentIdMapping
: Data is flat with parent ID references → bind

idMapping="TaskId" parentIdMapping="ParentId"

childMapping
: 数据为嵌套结构（每个父级包含
```
Children
```
列表）→ 绑定
```
childMapping="Children"
```

idMapping
+
parentIdMapping
: 数据为带父ID引用的扁平结构→ 绑定

idMapping="TaskId" parentIdMapping="ParentId"

Enable Editing with Toolbar

启用带工具栏的编辑

cshtml

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

Always set
isPrimaryKey="true"
on one column — editing and delete operations require it.

cshtml

<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"
— 编辑和删除操作需要此项。

Key Error Avoidance

关键错误规避

Do NOT enable paging and virtualization simultaneously
Do NOT set
```
isFrozen
```
and
```
frozenColumns
```
at the same time
```
showCheckbox
```
column must be defined only on the tree column
```
textAlign="Right"
```
is not applicable for the tree column
Do NOT enable
```
idMapping
```
and
```
childMapping
```
simultaneously

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

syncfusion-aspnetcore-tree-grid

Original

Translation

Syncfusion ASP.NET Core TreeGrid

Syncfusion ASP.NET Core TreeGrid

⚠️ Security & Trust Boundary

⚠️ 安全与信任边界

When to Use This Skill

何时使用此技能

Table of Contents

目录

Data Structure Rules

数据结构规则

Rule 1: childMapping is MANDATORY for Hierarchical Data

规则1：分层数据必须设置childMapping

Rule 2: Data Type Matching is MANDATORY

规则2：数据类型匹配是必填项

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

Data Binding

数据绑定

Columns

列配置

Sorting

排序

Filtering

筛选

Editing

编辑

Paging

分页

Selection

选择

Aggregates

聚合

Row Customization

行自定义

Cell Customization

单元格自定义

Export (Excel)

导出（Excel）

PDF Export

PDF导出

Print

打印

Clipboard

剪贴板

Scrolling

滚动

Adaptive Layout

自适应布局

Frozen Rows and Columns

冻结行和列

Styling and Appearance

样式与外观

Immutable Mode

不可变模式

Toolbar

工具栏

Context Menu

上下文菜单

Searching

搜索

Loading Animation

加载动画

Globalization & Localization

全球化与本地化

State Management

状态管理

Accessibility

可访问性

Properties & Configuration

属性与配置

Events & Lifecycle

事件与生命周期

Settings Classes & Enums Reference

设置类与枚举参考

Quick Start Example

When to use
`childMapping`
vs
`idMapping`

何时使用
`childMapping`
vs
`idMapping`