syncfusion-wpf-treegrid

实现 WPF TreeGrid（SfTreeGrid）

实现 Syncfusion® WPF TreeGrid 控件的综合指南。该控件面向数据，可通过树形结构和列显示自关联数据与分层数据。本技能提供有关设置、数据绑定、列配置、交互功能、数据操作、样式设置和高级功能的完整指南。

何时使用此技能

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

• 在网格中显示分层数据，并使用可展开／折叠的树形结构
• 绑定自关联数据（单个集合中的父子关系）
• 绑定嵌套集合，其中包含父子对象层次结构
• 为大型分层数据集实现按需加载
• 配置列，包括各种类型（文本、数值、日期时间、复选框、组合框）
• 在 TreeGrid 中启用编辑并进行验证
• 对分层数据实现排序和筛选
• 自定义选择行为（单选、多选、行、单元格）
• 根据数据或节点级别应用条件样式
• 合并 TreeGrid 行中跨列的单元格
• 将 TreeGrid 导出为 Excel 或 PDF 格式
• 使用 TreeGrid 控件实现 MVVM 模式
• 使用主题、样式和模板自定义外观

对于需要在交互丰富的网格界面中呈现分层数据或父子数据的任何 WPF 应用程序，本技能都必不可少。

组件概述

SfTreeGrid 控件提供：

• 分层数据显示： 自关联数据和嵌套集合绑定
• 多种列类型： 文本、数值、DateTime、CheckBox、ComboBox、Hyperlink 和 Template 列
• 交互功能： 编辑、选择、排序、筛选、拖放
• 数据操作： 排序、筛选，支持多个筛选级别（Root、All、Extended）
• 按需加载： 展开节点时高效加载子节点
• 单元格合并： 合并跨列的相邻单元格
• 导出功能： 导出为 Excel 和 PDF，并支持自定义
• 样式设置： 条件样式、主题、模板和视觉自定义
• MVVM 支持： 完全兼容 MVVM 模式，并支持命令绑定
• 性能： 虚拟化和优化渲染，适用于大型数据集

文档和导航指南

入门

📄 阅读： references/getting-started.md

从这里开始进行初始设置和基本实现：

• 程序集部署（Syncfusion.SfGrid.WPF、Syncfusion.Data.WPF、Syncfusion.Shared.WPF）
• 创建包含 TreeGrid 的 WPF 项目
• 通过 Designer、XAML 或代码隐藏添加控件
• TreeGrid 基本设置示例
• 简单的自关联数据和嵌套集合绑定

数据绑定和操作

数据绑定方式
📄 阅读： references/data-binding.md

• 自关联数据绑定（ParentPropertyName、ChildPropertyName）
• 嵌套集合绑定（ChildPropertyName）
• 支持 IEnumerable 集合
• 动态数据对象绑定
• INotifyCollectionChanged 和 ObservableCollection
• 数据刷新和更新

按需加载
📄 阅读： references/load-on-demand.md

• 使用 RequestTreeItems 事件按需加载
• 在 MVVM 场景中使用 LoadOnDemandCommand
• 展开节点时延迟加载子节点
• 针对大型数据集进行性能优化
• 显示节点填充指示器

列配置

列基础知识
📄 阅读： references/columns.md

• 添加和移除列
• AutoGenerateColumns 与手动配置
• 列属性（HeaderText、MappingName、Width、Alignment）
• 列可见性和冻结列
• 列重新排序和调整大小
• 文本换行和截断

列类型
📄 阅读： references/column-types.md

• 用于字符串数据的 TreeGridTextColumn
• 支持数字格式设置的 TreeGridNumericColumn
• 支持日期格式的 TreeGridDateTimeColumn
• 用于布尔值的 TreeGridCheckBoxColumn
• 用于下拉选择的 TreeGridComboBoxColumn
• 用于可点击链接的 TreeGridHyperlinkColumn
• 用于自定义内容的 TreeGridTemplateColumn
• 创建自定义列类型

列大小调整
📄 阅读： references/column-sizing.md

• ColumnSizer 属性（Auto、Star、SizeToCells、SizeToHeader）
• 根据内容自动调整列宽
• 手动指定宽度
• 用户调整大小的行为
• 最小和最大宽度限制
• 填充剩余空间的策略

交互功能

编辑
📄 阅读： references/editing.md

• 网格和列级别的 AllowEditing 属性
• 编辑模式（OnTap、OnDoubleTap）
• 编辑触发条件和编辑模板自定义
• BeginEdit 和 EndEdit 事件
• 以编程方式编辑（BeginEdit、EndEdit、CurrentCell）
• 编辑过程中的验证

数据验证
📄 阅读： references/data-validation.md

• IDataErrorInfo 验证接口
• 支持 INotifyDataErrorInfo
• 单元格级和行级验证
• 自定义验证规则
• 自定义验证错误显示
• 处理验证错误

选择
📄 阅读： references/selection.md

• SelectionMode（Single、Multiple、Extended、None）
• SelectionUnit（Row、Cell、Any）
• SelectedItem 和 SelectedItems 绑定
• CurrentCell 和 CurrentItem 属性
• 以编程方式进行选择
• SelectionChanged 和 CurrentCellActivated 事件

单元格合并
📄 阅读： references/merge-cells.md

• 使用 QueryCoveredRange 事件合并单元格
• 按固定范围逐列合并
• 根据单元格内容合并
• 合并单元格中的导航和选择
• 单元格合并的性能注意事项

数据操作

排序
📄 阅读： references/sorting.md

• AllowSorting 属性（网格和列级别）
• 单列和多列排序
• 三态排序（升序、降序、不排序）
• 网格和列级别的初始排序方向（InitialSortDirection）
• 使用 SortColumnDescriptions 以编程方式排序
• 使用 IComparer 实现自定义排序逻辑
• SortColumnsChanging 和 SortColumnsChanged 事件

筛选
📄 阅读： references/filtering.md

• 使用 FilterLevel（Root、All、Extended）进行分层筛选
• 带筛选行的高级筛选界面
• 使用 FilterPredicates 以编程方式筛选
• 自定义筛选逻辑
• FilterChanging 和 FilterChanged 事件
• 清除和保留筛选条件

样式与自定义

条件样式
📄 阅读： references/conditional-styling.md

• 用于行和单元格样式设置的 StyleSelector
• 用于按行设置格式的 RowStyleSelector
• 用于按单元格设置格式的 CellStyleSelector
• 根据数据值应用条件格式
• 基于节点层级的样式（父级与子级）
• 交替行样式

样式和模板
📄 阅读： references/styles-and-templates.md

• 自定义 CellTemplate 和 EditTemplate
• 列标题的 HeaderTemplate
• 展开/折叠按钮的 ExpanderTemplate
• 自定义 RowHeaderTemplate
• 单元格和行样式设置
• 视觉状态和触发器
• 主题集成

高级功能

导出和打印
📄 阅读： references/export-and-printing.md

• 导出为 Excel（ExportToExcel 方法）
• 导出为 PDF（ExportToPdf 方法）
• 自定义 TreeGridExcelExportingOptions
• 自定义 TreeGridPdfExportingOptions
• 打印功能（PrintSettings）
• 导出特定节点和列

高级配置
📄 阅读： references/advanced-features.md

• 使用 ICommand 实现 MVVM 模式
• 自定义 GridLinesVisibility（Both、Horizontal、Vertical、None）
• 序列化和反序列化（Save/LoadSettings）
• 本地化（ResourceManager）
• 支持 UI Automation，实现无障碍访问
• 主题（MaterialLight、MaterialDark、Office2019 等）
• 辅助方法和实用工具
• 用于选择节点的 NodeCheckBox
• 自定义 ToolTip

快速入门示例

基本的自关联 TreeGrid

<Window x:Class="TreeGridSample.MainWindow"
        xmlns="http://schemas.microsoft.com/winfx/2006/xaml/presentation"
        xmlns:x="http://schemas.microsoft.com/winfx/2006/xaml"
        xmlns:syncfusion="http://schemas.syncfusion.com/wpf">
    
    <syncfusion:SfTreeGrid Name="treeGrid"
                           AutoGenerateColumns="True"
                           ChildPropertyName="Children"
                           ItemsSource="{Binding Employees}"
                           AllowSorting="True"
                           AllowFiltering="True"
                           AllowEditing="True">
    </syncfusion:SfTreeGrid>
</Window>

using Syncfusion.UI.Xaml.TreeGrid;
using System.Collections.ObjectModel;

namespace TreeGridSample
{
    public class Employee
    {
        public int EmployeeID { get; set; }
        public string FirstName { get; set; }
        public string LastName { get; set; }
        public string Title { get; set; }
        public int ReportsTo { get; set; }
        public ObservableCollection<Employee> Children { get; set; }
        
        public Employee()
        {
            Children = new ObservableCollection<Employee>();
        }
    }

    public class EmployeeViewModel
    {
        public ObservableCollection<Employee> Employees { get; set; }
        
        public EmployeeViewModel()
        {
            Employees = new ObservableCollection<Employee>();
            PopulateData();
        }
        
        private void PopulateData()
        {
            var ceo = new Employee
            {
                EmployeeID = 1,
                FirstName = "Robert",
                LastName = "King",
                Title = "CEO"
            };
            
            ceo.Children.Add(new Employee
            {
                EmployeeID = 2,
                FirstName = "David",
                LastName = "Smith",
                Title = "VP of Sales",
                ReportsTo = 1
            });
            
            ceo.Children.Add(new Employee
            {
                EmployeeID = 3,
                FirstName = "Nancy",
                LastName = "Davolio",
                Title = "VP of Marketing",
                ReportsTo = 1
            });
            
            Employees.Add(ceo);
        }
    }
}

常见模式

模式 1：自关联数据绑定

适用于父子关系存在于同一集合中的数据：

public class Task
{
    public int TaskID { get; set; }
    public string TaskName { get; set; }
    public int? ParentID { get; set; }  // Nullable for root items
}

// ViewModel
public ObservableCollection<Task> Tasks { get; set; }

<syncfusion:SfTreeGrid Name="treeGrid"
                       ItemsSource="{Binding Tasks}"
                       ParentPropertyName="ParentID"
                       SelfRelationRootValue="-1"
                       ChildPropertyName="TaskID">
</syncfusion:SfTreeGrid>

模式 2：嵌套集合绑定

适用于具有显式子集合的数据：

public class Folder
{
    public string FolderName { get; set; }
    public ObservableCollection<Folder> SubFolders { get; set; }
}

<syncfusion:SfTreeGrid Name="treeGrid"
                       ItemsSource="{Binding Folders}"
                       ChildPropertyName="SubFolders">
</syncfusion:SfTreeGrid>

模式 3：使用 RequestTreeItems 按需加载

适用于父节点展开时才加载子节点的大型数据集：

treeGrid.RequestTreeItems += TreeGrid_RequestTreeItems;

private void TreeGrid_RequestTreeItems(object sender, TreeGridRequestTreeItemsEventArgs e)
{
    if (e.ParentItem == null)
    {
        // Load root nodes
        e.ChildItems = GetRootNodes();
    }
    else
    {
        // Load child nodes for expanded parent
        var parent = e.ParentItem as BusinessObject;
        e.ChildItems = GetChildNodes(parent.ID);
    }
}

模式 4：自定义列定义

<syncfusion:SfTreeGrid ItemsSource="{Binding Employees}"
                       AutoGenerateColumns="False">
    <syncfusion:SfTreeGrid.Columns>
        <syncfusion:TreeGridTextColumn HeaderText="Name" 
                                       MappingName="FirstName"
                                       Width="150"/>
        <syncfusion:TreeGridNumericColumn HeaderText="Age" 
                                          MappingName="Age"
                                          NumberDecimalDigits="0"/>
        <syncfusion:TreeGridDateTimeColumn HeaderText="DOB" 
                                           MappingName="DateOfBirth"
                                           Pattern="ShortDate"/>
        <syncfusion:TreeGridCheckBoxColumn HeaderText="Active" 
                                           MappingName="IsActive"/>
    </syncfusion:SfTreeGrid.Columns>
</syncfusion:SfTreeGrid>

模式 5：MVVM 命令绑定

<syncfusion:SfTreeGrid ItemsSource="{Binding Employees}"
                       ChildPropertyName="Children">
    <syncfusion:SfTreeGrid.RecordContextMenu>
        <ContextMenu>
            <MenuItem Header="Add Child" 
                      Command="{Binding AddChildCommand}"
                      CommandParameter="{Binding}"/>
            <MenuItem Header="Delete" 
                      Command="{Binding DeleteCommand}"
                      CommandParameter="{Binding}"/>
        </ContextMenu>
    </syncfusion:SfTreeGrid.RecordContextMenu>
</syncfusion:SfTreeGrid>

public class EmployeeViewModel : INotifyPropertyChanged
{
    public ICommand AddChildCommand { get; set; }
    public ICommand DeleteCommand { get; set; }
    
    public EmployeeViewModel()
    {
        AddChildCommand = new RelayCommand(AddChild);
        DeleteCommand = new RelayCommand(Delete);
    }
    
    private void AddChild(object parameter)
    {
        var parent = parameter as Employee;
        if (parent != null)
        {
            parent.Children.Add(new Employee { /* ... */ });
        }
    }
}

关键属性

基本属性

属性	类型	描述
ItemsSource	IEnumerable	TreeGrid 的数据源
ChildPropertyName	string	子集合的属性名称
ParentPropertyName	string	父级 ID 的属性名称（自关联）
SelfRelationRootValue	object	指示根级节点的值
AutoGenerateColumns	bool	根据数据源自动生成列
Columns	TreeGridColumns	列定义集合

行为属性

属性	类型	描述
AllowEditing	bool	启用/禁用单元格编辑
AllowSorting	bool	启用/禁用排序
AllowFiltering	bool	启用/禁用筛选
FilterLevel	FilterLevel	筛选范围（Root、All、Extended）
SelectionMode	GridSelectionMode	选择模式（Single、Multiple、Extended）
SelectionUnit	GridSelectionUnit	选择单位（Row、Cell、Any）
AutoExpandMode	AutoExpandMode	自动展开行为（RootNodesExpanded、AllNodesExpanded）
ExpanderPosition	ExpanderPosition	展开/折叠图标的位置（Start、End）

显示属性

属性	类型	描述
GridLinesVisibility	GridLinesVisibility	网格线显示方式（Both、Horizontal、Vertical、None）
ColumnSizer	GridLengthUnitType	列自动调整大小策略
RowHeight	double	每行的高度
HeaderRowHeight	double	表头行的高度
IndentColumnWidth	double	每个层级的缩进宽度

常见用例

1. 员工层级管理

以可展开的树形格式显示组织结构，包括员工、经理和部门。

2. 文件系统浏览器

以层级结构显示文件夹和文件，并为大型目录树提供按需加载功能。

3. 项目任务管理

显示项目、子项目、任务和子任务，并支持状态跟踪、编辑和条件样式。

4. 物料清单（BOM）

以层级视图显示产品装配结构，包括组件、子组件、数量和成本。

5. 类别-产品目录

显示产品类别、子类别和产品，并支持筛选、排序和导出功能。

6. 账户层级结构

显示具有父子关系的财务账户树，并支持余额计算和下钻功能。

7. 多级审批工作流

通过状态指示器、条件样式和交互式编辑跟踪审批层级。

8. 地理数据组织

以分层格式显示国家、州和城市，并提供数据可视化和导出功能。

性能注意事项

• 对总节点数超过 1,000 的数据集，使用按需加载
• 启用虚拟化（默认已启用），实现流畅滚动
• 在频繁更新的单元格中避免使用复杂模板
• 使用 ItemsSourceChanged 事件，避免频繁重新绑定
• 修改多个节点时批量更新
• 不需要时禁用实时更新（LiveNodeUpdateMode）
• 根据数据结构优化 FilterLevel 的选择

相关技能

• 实现 Syncfusion WPF 组件 - 父级库技能
• 实现数据网格（未来提供）- 用于显示扁平网格数据
• 实现图表 - 已在 ../../data-visualization/implementing-charts/ 提供

支持资源

• 官方文档： https://help.syncfusion.com/wpf/treegrid/overview
• API 参考： https://help.syncfusion.com/cr/wpf/Syncfusion.UI.Xaml.TreeGrid.html
• 社区论坛： https://www.syncfusion.com/forums/wpf
• 示例浏览器： 可通过 Syncfusion Control Panel 使用

---

后续步骤： 根据实现需求，导航至上方对应的参考文件。从 getting-started.md 开始进行初始设置，然后按需探索数据绑定、列配置和高级功能。