syncfusion-winui-treegrid
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseImplementing Syncfusion WinUI TreeGrid
实现Syncfusion WinUI TreeGrid
When to Use This Skill
适用场景
Use this skill when you need to:
- Display hierarchical or self-relational data in a tree-structured grid
- Create data grids with parent-child relationships
- Implement expandable/collapsible rows with nested data
- Build organizational charts or employee hierarchies in grid format
- Display file system structures with grid features
- Work with category hierarchies, bill of materials, or nested classifications
- Need advanced grid features (sorting, filtering, editing) on tree-structured data
- Visualize multi-level data with column-based representation
当你需要完成以下需求时可使用本指南:
- 在树形结构表格中展示层级或自关联数据
- 创建具备父子关系的数据表格
- 实现支持嵌套数据的可展开/折叠行
- 以表格形式构建组织架构图或员工层级关系
- 展示具备表格特性的文件系统结构
- 处理类别层级、物料清单或嵌套分类
- 为树形结构数据提供高级表格功能(排序、筛选、编辑)
- 以基于列的形式可视化多层级数据
Component Overview
组件概述
The Syncfusion® WinUI TreeGrid (SfTreeGrid) is a data-oriented control that displays self-relational or hierarchical data in a tree structure with grid capabilities. It combines the tree view's expandable/collapsible navigation with the data grid's rich feature set.
Control Name:
Namespace:
NuGet Package:
Platform: WinUI 3 (Windows App SDK)
SfTreeGridNamespace:
Syncfusion.UI.Xaml.TreeGridNuGet Package:
Syncfusion.Grid.WinUIPlatform: WinUI 3 (Windows App SDK)
Syncfusion® WinUI TreeGrid(SfTreeGrid)是一款面向数据的控件,可在具备表格能力的树形结构中展示自关联或层级数据。它结合了树视图的可展开/折叠导航能力与数据表格的丰富功能集。
控件名称:
命名空间:
NuGet包:
支持平台: WinUI 3 (Windows App SDK)
SfTreeGrid命名空间:
Syncfusion.UI.Xaml.TreeGridNuGet包:
Syncfusion.Grid.WinUI支持平台: WinUI 3 (Windows App SDK)
Key Capabilities
核心能力
- Data Binding: Self-relational and nested collection support
- Columns: 8 built-in column types with auto-generation
- Editing: Built-in editors for all column types with validation
- Sorting: Single and multi-column sorting
- Filtering: Excel-inspired filter UI
- Selection: Row and cell selection modes
- Node Features: Checkboxes, load-on-demand, expand/collapse
- Row Operations: Drag-and-drop, merge cells
- Data Operations: Clipboard operations, Excel export
- Styling: Conditional styling, custom templates
- Advanced: Context menus, tooltips, MVVM support
- 数据绑定: 支持自关联和嵌套集合
- 列类型: 8种内置列类型,支持自动生成
- 编辑能力: 所有列类型都配备内置编辑器,支持校验
- 排序: 支持单列和多列排序
- 筛选: 类Excel的筛选UI
- 选择: 支持行选择和单元格选择模式
- 节点功能: 复选框、按需加载、展开/折叠
- 行操作: 拖放、单元格合并
- 数据操作: 剪贴板操作、Excel导出
- 样式: 条件样式、自定义模板
- 高级功能: 上下文菜单、工具提示、MVVM支持
Documentation and Navigation Guide
文档与导航指南
Getting Started
入门指南
📄 Read: references/getting-started.md
- Creating WinUI TreeGrid application setup
- NuGet package installation (Syncfusion.Grid.WinUI)
- Namespace imports and basic initialization
- First TreeGrid with minimal XAML/C# code
- Quick render verification
📄 阅读: references/getting-started.md
- WinUI TreeGrid应用创建与环境配置
- NuGet包安装(Syncfusion.Grid.WinUI)
- 命名空间导入与基础初始化
- 用最少的XAML/C#代码实现第一个TreeGrid
- 快速渲染验证
Data Binding
数据绑定
📄 Read: references/data-binding.md
- Binding self-relational data (ParentPropertyName, ChildPropertyName)
- SelfRelationRootValue configuration for root nodes
- Binding nested collections (hierarchical objects)
- Creating data models and ViewModels
- ItemsSource binding patterns
- Tree structure formation examples
📄 阅读: references/data-binding.md
- 自关联数据绑定(ParentPropertyName、ChildPropertyName)
- 根节点的SelfRelationRootValue配置
- 嵌套集合(层级对象)绑定
- 数据模型与ViewModel创建
- ItemsSource绑定模式
- 树形结构构建示例
Columns and Column Types
列与列类型
📄 Read: references/columns.md
- 8 built-in column types (Text, Numeric, Date, Time, CheckBox, ComboBox, Hyperlink, Template)
- Auto-generating columns vs manual definition
- AutoGeneratingColumn event for customization
- Column type selection based on data types
- TreeGridColumn base class and properties
📄 阅读: references/columns.md
- 8种内置列类型(文本、数值、日期、时间、复选框、下拉框、超链接、模板)
- 自动生成列 vs 手动定义列
- 用于自定义的AutoGeneratingColumn事件
- 基于数据类型选择列类型
- TreeGridColumn基类与属性
Column Configuration
列配置
📄 Read: references/column-configuration.md
- Column sizing and width modes (Auto, Star, Fill)
- Header customization and formatting
- MappingName for data binding
- Column visibility and ordering
- Frozen columns for fixed display
- Cell and edit templates
📄 阅读: references/column-configuration.md
- 列尺寸与宽度模式(自动、比例、填充)
- 表头自定义与格式化
- 用于数据绑定的MappingName
- 列可见性与排序
- 固定展示的冻结列
- 单元格与编辑模板
Editing and Validation
编辑与校验
📄 Read: references/editing.md
- Enabling editing (AllowEditing property)
- Column-level editing control
- Edit mode configuration
- CurrentCellBeginEdit and CurrentCellEndEdit events
- Data validation during editing
- Programmatic editing operations
- Custom editor templates
📄 阅读: references/editing.md
- 启用编辑(AllowEditing属性)
- 列级编辑控制
- 编辑模式配置
- CurrentCellBeginEdit与CurrentCellEndEdit事件
- 编辑过程中的数据校验
- 程序化编辑操作
- 自定义编辑器模板
Selection
选择功能
📄 Read: references/selection.md
- Selection modes (Single, Multiple, Extended, None)
- Row selection vs cell selection (SelectionUnit)
- SelectionChanging and SelectionChanged events
- Programmatic selection APIs
- SelectedItem, SelectedItems properties
- Keyboard navigation patterns
📄 阅读: references/selection.md
- 选择模式(单选、多选、扩展选择、无选择)
- 行选择 vs 单元格选择(SelectionUnit)
- SelectionChanging与SelectionChanged事件
- 程序化选择API
- SelectedItem、SelectedItems属性
- 键盘导航模式
Sorting and Filtering
排序与筛选
📄 Read: references/sorting-filtering.md
- Single and multi-column sorting
- SortColumnDescriptions collection
- SortColumnChanging/Changed events
- Custom sorting logic
- Excel-inspired filter UI (AllowFiltering)
- FilterChanging/Changed events
- Programmatic filtering with predicates
- Filter customization
📄 阅读: references/sorting-filtering.md
- 单列与多列排序
- SortColumnDescriptions集合
- SortColumnChanging/Changed事件
- 自定义排序逻辑
- 类Excel筛选UI(AllowFiltering)
- FilterChanging/Changed事件
- 使用断言的程序化筛选
- 筛选自定义
Row Operations
行操作
📄 Read: references/row-operations.md
- Row height customization
- Row drag-and-drop functionality
- Drag-drop events and validation
- Merge cells feature
- Cell merging configuration
- Conditional row styling
- Row validation rules
📄 阅读: references/row-operations.md
- 行高自定义
- 行拖放功能
- 拖放事件与校验
- 单元格合并功能
- 单元格合并配置
- 条件行样式
- 行校验规则
Node Features
节点功能
📄 Read: references/node-features.md
- Node checkboxes for selection
- Recursive checking behavior
- NodeCheckStateChanging/Changed events
- Load-on-demand (lazy loading child nodes)
- LoadOnDemandCommand
- HasChildNodes property
- Dynamic child population
📄 阅读: references/node-features.md
- 用于选择的节点复选框
- 递归勾选行为
- NodeCheckStateChanging/Changed事件
- 按需加载(懒加载子节点)
- LoadOnDemandCommand
- HasChildNodes属性
- 动态子节点填充
Data Operations
数据操作
📄 Read: references/data-operations.md
- Clipboard operations (copy/paste)
- CopyOption property configuration
- CopyGridCellContent event
- Export to Excel functionality
- ExcelExportingOptions
- Exporting selected items
- Export customization and formatting
📄 阅读: references/data-operations.md
- 剪贴板操作(复制/粘贴)
- CopyOption属性配置
- CopyGridCellContent事件
- Excel导出功能
- ExcelExportingOptions
- 导出选中项
- 导出自定义与格式化
Styling and Customization
样式与自定义
📄 Read: references/styling-customization.md
- Conditional styling based on data
- Cell and row styling
- QueryCellStyle and QueryRowStyle events
- GridLines customization
- GridLinesVisibility property
- UI customization and templates
- Theme integration
📄 阅读: references/styling-customization.md
- 基于数据的条件样式
- 单元格与行样式
- QueryCellStyle与QueryRowStyle事件
- 网格线自定义
- GridLinesVisibility属性
- UI自定义与模板
- 主题集成
Advanced Features
高级功能
📄 Read: references/advanced-features.md
- Context flyout menus
- Custom context menu items
- Tooltips for cells and headers
- Custom tooltip templates
- MVVM pattern support
- Commands and data binding
- Helper methods and utilities
- Performance optimization techniques
📄 阅读: references/advanced-features.md
- 上下文浮出菜单
- 自定义上下文菜单项
- 单元格与表头的工具提示
- 自定义工具提示模板
- MVVM模式支持
- 命令与数据绑定
- 辅助方法与工具类
- 性能优化技巧
Quick Start Example
快速入门示例
Self-Relational Data
自关联数据
xaml
<Window
x:Class="TreeGridDemo.MainWindow"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:treeGrid="using:Syncfusion.UI.Xaml.TreeGrid">
<Window.DataContext>
<local:ViewModel/>
</Window.DataContext>
<Grid>
<treeGrid:SfTreeGrid x:Name="treeGrid"
ItemsSource="{Binding Employees}"
ParentPropertyName="ID"
ChildPropertyName="ReportsTo"
SelfRelationRootValue="-1"
AutoExpandMode="RootNodesExpanded" />
</Grid>
</Window>csharp
public class EmployeeInfo
{
public int ID { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public string Title { get; set; }
public double Salary { get; set; }
public int ReportsTo { get; set; }
}
public class ViewModel
{
public ObservableCollection<EmployeeInfo> Employees { get; set; }
public ViewModel()
{
Employees = new ObservableCollection<EmployeeInfo>
{
new EmployeeInfo { ID = 1, FirstName = "John", LastName = "Doe",
Title = "CEO", Salary = 200000, ReportsTo = -1 },
new EmployeeInfo { ID = 2, FirstName = "Jane", LastName = "Smith",
Title = "Manager", Salary = 120000, ReportsTo = 1 },
new EmployeeInfo { ID = 3, FirstName = "Bob", LastName = "Johnson",
Title = "Developer", Salary = 80000, ReportsTo = 2 }
};
}
}xaml
<Window
x:Class="TreeGridDemo.MainWindow"
xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
xmlns:treeGrid="using:Syncfusion.UI.Xaml.TreeGrid">
<Window.DataContext>
<local:ViewModel/>
</Window.DataContext>
<Grid>
<treeGrid:SfTreeGrid x:Name="treeGrid"
ItemsSource="{Binding Employees}"
ParentPropertyName="ID"
ChildPropertyName="ReportsTo"
SelfRelationRootValue="-1"
AutoExpandMode="RootNodesExpanded" />
</Grid>
</Window>csharp
public class EmployeeInfo
{
public int ID { get; set; }
public string FirstName { get; set; }
public string LastName { get; set; }
public string Title { get; set; }
public double Salary { get; set; }
public int ReportsTo { get; set; }
}
public class ViewModel
{
public ObservableCollection<EmployeeInfo> Employees { get; set; }
public ViewModel()
{
Employees = new ObservableCollection<EmployeeInfo>
{
new EmployeeInfo { ID = 1, FirstName = "John", LastName = "Doe",
Title = "CEO", Salary = 200000, ReportsTo = -1 },
new EmployeeInfo { ID = 2, FirstName = "Jane", LastName = "Smith",
Title = "Manager", Salary = 120000, ReportsTo = 1 },
new EmployeeInfo { ID = 3, FirstName = "Bob", LastName = "Johnson",
Title = "Developer", Salary = 80000, ReportsTo = 2 }
};
}
}Nested Collection Data
嵌套集合数据
csharp
public class PersonInfo
{
public string FirstName { get; set; }
public string LastName { get; set; }
public double Salary { get; set; }
public ObservableCollection<PersonInfo> Children { get; set; }
}xaml
<treeGrid:SfTreeGrid x:Name="treeGrid"
ItemsSource="{Binding PersonDetails}"
ChildPropertyName="Children" />csharp
public class PersonInfo
{
public string FirstName { get; set; }
public string LastName { get; set; }
public double Salary { get; set; }
public ObservableCollection<PersonInfo> Children { get; set; }
}xaml
<treeGrid:SfTreeGrid x:Name="treeGrid"
ItemsSource="{Binding PersonDetails}"
ChildPropertyName="Children" />Common Patterns
常见使用模式
Self-Relational Data Structure
自关联数据结构
Use when data objects reference each other via ID/ParentID:
csharp
// Each employee has an ID and ReportsTo (parent ID)
ParentPropertyName = "ID"
ChildPropertyName = "ReportsTo"
SelfRelationRootValue = -1 // Root nodes have ReportsTo = -1当数据对象通过ID/ParentID互相引用时使用:
csharp
// Each employee has an ID and ReportsTo (parent ID)
ParentPropertyName = "ID"
ChildPropertyName = "ReportsTo"
SelfRelationRootValue = -1 // Root nodes have ReportsTo = -1Nested Collection Structure
嵌套集合结构
Use when data objects contain child collections:
csharp
// Each person has a Children property containing child objects
ChildPropertyName = "Children"
// No ParentPropertyName needed当数据对象包含子集合时使用:
csharp
// Each person has a Children property containing child objects
ChildPropertyName = "Children"
// No ParentPropertyName neededColumn Auto-Generation Control
列自动生成控制
xaml
<!-- Auto-generate columns from data properties -->
<treeGrid:SfTreeGrid AutoGenerateColumns="True" />
<!-- Define columns manually for full control -->
<treeGrid:SfTreeGrid AutoGenerateColumns="False">
<treeGrid:SfTreeGrid.Columns>
<treeGrid:TreeGridTextColumn MappingName="FirstName" HeaderText="First Name"/>
<treeGrid:TreeGridNumericColumn MappingName="Salary" DisplayNumberFormat="C2"/>
</treeGrid:SfTreeGrid.Columns>
</treeGrid:SfTreeGrid>xaml
<!-- Auto-generate columns from data properties -->
<treeGrid:SfTreeGrid AutoGenerateColumns="True" />
<!-- Define columns manually for full control -->
<treeGrid:SfTreeGrid AutoGenerateColumns="False">
<treeGrid:SfTreeGrid.Columns>
<treeGrid:TreeGridTextColumn MappingName="FirstName" HeaderText="First Name"/>
<treeGrid:TreeGridNumericColumn MappingName="Salary" DisplayNumberFormat="C2"/>
</treeGrid:SfTreeGrid.Columns>
</treeGrid:SfTreeGrid>MVVM Data Binding
MVVM数据绑定
csharp
public class ViewModel : INotifyPropertyChanged
{
private ObservableCollection<DataModel> _items;
public ObservableCollection<DataModel> Items
{
get => _items;
set
{
_items = value;
OnPropertyChanged();
}
}
public event PropertyChangedEventHandler PropertyChanged;
protected void OnPropertyChanged([CallerMemberName] string name = null)
{
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
}
}csharp
public class ViewModel : INotifyPropertyChanged
{
private ObservableCollection<DataModel> _items;
public ObservableCollection<DataModel> Items
{
get => _items;
set
{
_items = value;
OnPropertyChanged();
}
}
public event PropertyChangedEventHandler PropertyChanged;
protected void OnPropertyChanged([CallerMemberName] string name = null)
{
PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
}
}Expand/Collapse Control
展开/折叠控制
csharp
// Auto-expand modes
AutoExpandMode = AutoExpandMode.AllNodesExpanded; // All expanded
AutoExpandMode = AutoExpandMode.RootNodesExpanded; // Only root
AutoExpandMode = AutoExpandMode.None; // All collapsed
// Programmatic control
treeGrid.ExpandNode(node);
treeGrid.CollapseNode(node);
treeGrid.ExpandAllNodes();
treeGrid.CollapseAllNodes();csharp
// Auto-expand modes
AutoExpandMode = AutoExpandMode.AllNodesExpanded; // All expanded
AutoExpandMode = AutoExpandMode.RootNodesExpanded; // Only root
AutoExpandMode = AutoExpandMode.None; // All collapsed
// Programmatic control
treeGrid.ExpandNode(node);
treeGrid.CollapseNode(node);
treeGrid.ExpandAllNodes();
treeGrid.CollapseAllNodes();Key Properties
核心属性
Data Binding Properties
数据绑定属性
-
ItemsSource - Data source (IEnumerable)
- When: Always required for data binding
- Why: Provides the data to display
-
ChildPropertyName - Property containing child collection or parent reference
- When: Required for all tree structures
- Why: Defines the tree relationship
-
ParentPropertyName - Property containing unique identifier (self-relational only)
- When: Only for self-relational data
- Why: Identifies parent nodes
-
SelfRelationRootValue - Value indicating root nodes (self-relational only)
- When: With self-relational data
- Why: Identifies which nodes are roots (default: null)
-
ItemsSource - 数据源(IEnumerable)
- 适用场景:数据绑定必填项
- 作用:提供需要展示的数据
-
ChildPropertyName - 存储子集合或父引用的属性
- 适用场景:所有树形结构必填
- 作用:定义树状关系
-
ParentPropertyName - 存储唯一标识的属性(仅自关联数据需要)
- 适用场景:仅处理自关联数据时需要
- 作用:识别父节点
-
SelfRelationRootValue - 标识根节点的值(仅自关联数据需要)
- 适用场景:处理自关联数据时使用
- 作用:识别哪些节点是根节点(默认值:null)
Display Properties
展示属性
-
AutoGenerateColumns - Auto-create columns from properties (default: true)
- When: Set false for manual column control
- Why: Automatic vs explicit column definition
-
AutoExpandMode - Initial expand state
- When: Control initial tree visibility
- Why: User experience for data exploration
-
ColumnWidthMode - How columns calculate width
- When: Control column sizing behavior
- Why: Auto, Star, or fixed widths
-
AutoGenerateColumns - 从属性自动创建列(默认值:true)
- 适用场景:需要手动控制列时设置为false
- 作用:选择自动生成列还是显式定义列
-
AutoExpandMode - 初始展开状态
- 适用场景:控制初始树形展示状态
- 作用:优化数据浏览的用户体验
-
ColumnWidthMode - 列宽度计算规则
- 适用场景:控制列尺寸行为
- 作用:支持自动、比例或固定宽度
Feature Properties
功能属性
-
AllowEditing - Enable cell editing (default: false)
- When: Editable grid needed
- Why: In-place data modification
-
AllowFiltering - Enable filter UI (default: false)
- When: Large datasets need filtering
- Why: Excel-style data filtering
-
SelectionMode - Row/cell selection type
- When: Control selection behavior
- Why: Single, Multiple, Extended, or None
-
SelectionUnit - Select rows or cells
- When: Define selection granularity
- Why: Row vs cell-level selection
-
AllowEditing - 启用单元格编辑(默认值:false)
- 适用场景:需要可编辑表格时
- 作用:支持就地修改数据
-
AllowFiltering - 启用筛选UI(默认值:false)
- 适用场景:大数据集需要筛选时
- 作用:提供Excel风格的数据筛选
-
SelectionMode - 行/单元格选择类型
- 适用场景:控制选择行为
- 作用:支持单选、多选、扩展选择或无选择
-
SelectionUnit - 选择行还是单元格
- 适用场景:定义选择粒度
- 作用:选择行级别还是单元格级别的选择
Common Use Cases
常见用例
Organizational Hierarchy
组织层级架构
Display company structure with employees reporting to managers:
csharp
ParentPropertyName = "EmployeeID"
ChildPropertyName = "ManagerID"展示公司结构,员工向经理汇报:
csharp
ParentPropertyName = "EmployeeID"
ChildPropertyName = "ManagerID"File System Browser
文件系统浏览器
Show folders and files in tree structure:
csharp
ChildPropertyName = "SubItems" // Nested collection以树形结构展示文件夹和文件:
csharp
ChildPropertyName = "SubItems" // Nested collectionCategory Management
分类管理
Display product categories with subcategories:
csharp
ChildPropertyName = "SubCategories"展示产品分类与子分类:
csharp
ChildPropertyName = "SubCategories"Bill of Materials (BOM)
物料清单(BOM)
Show product assemblies and components:
csharp
ParentPropertyName = "PartID"
ChildPropertyName = "ParentPartID"展示产品装配与组件:
csharp
ParentPropertyName = "PartID"
ChildPropertyName = "ParentPartID"Task/Project Management
任务/项目管理
Display tasks with subtasks:
csharp
ChildPropertyName = "SubTasks"展示任务与子任务:
csharp
ChildPropertyName = "SubTasks"Geographic Hierarchies
地理层级
Show countries > states > cities:
csharp
ChildPropertyName = "Children"展示国家 > 省份 > 城市:
csharp
ChildPropertyName = "Children"Troubleshooting
问题排查
Tree Structure Not Forming
树形结构未生成
- Verify ParentPropertyName and ChildPropertyName are set correctly
- Check SelfRelationRootValue matches your data's root indicator
- Ensure data relationships are properly defined
- 确认ParentPropertyName和ChildPropertyName设置正确
- 检查SelfRelationRootValue是否与数据中的根节点标识匹配
- 确保数据关系定义正确
Columns Not Appearing
列未展示
- Set AutoGenerateColumns = True, or define columns manually
- Check MappingName matches property names exactly (case-sensitive)
- Verify data source is bound to ItemsSource
- 设置AutoGenerateColumns = True,或手动定义列
- 检查MappingName是否与属性名完全匹配(大小写敏感)
- 确认数据源已绑定到ItemsSource
Performance Issues with Large Datasets
大数据集性能问题
- Enable load-on-demand for lazy loading
- Use on-demand mode to defer child node loading
- Consider data virtualization for very large trees
- 启用按需加载实现懒加载
- 使用按需模式延迟子节点加载
- 超大树结构可考虑数据虚拟化
Editing Not Working
编辑功能不生效
- Set AllowEditing = True on TreeGrid
- Check column-level AllowEditing property
- Ensure data objects implement INotifyPropertyChanged
Next Steps: Read the getting-started guide, then explore feature-specific references based on your requirements.
- 在TreeGrid上设置AllowEditing = True
- 检查列级的AllowEditing属性
- 确保数据对象实现了INotifyPropertyChanged
后续步骤: 阅读入门指南,然后根据你的需求探索对应功能的参考文档。