syncfusion-winui-treegrid

实现 Syncfusion WinUI TreeGrid

何时使用此技能

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

• 在树状网格中显示分层数据或自关联数据
• 创建具有父子关系的数据网格
• 实现可展开／折叠的行及嵌套数据
• 以网格格式构建组织架构图或员工层级结构
• 使用网格功能显示文件系统结构
• 处理类别层级、物料清单或嵌套分类
• 需要在树状数据上使用高级网格功能（排序、筛选、编辑）
• 以基于列的形式可视化多层级数据

组件概述

Syncfusion® WinUI TreeGrid（SfTreeGrid）是一种面向数据的控件，可在树状结构中显示自关联数据或分层数据，并提供网格功能。它将树视图的可展开／折叠导航与数据网格丰富的功能集结合起来。

控件名称： SfTreeGrid
命名空间： Syncfusion.UI.Xaml.TreeGrid
NuGet 包： Syncfusion.Grid.WinUI
平台： WinUI 3（Windows App SDK）

主要功能

• 数据绑定： 支持自关联数据和嵌套集合
• 列： 8 种内置列类型，支持自动生成
• 编辑： 所有列类型均内置编辑器，并支持验证
• 排序： 单列和多列排序
• 筛选： 受 Excel 启发的筛选 UI
• 选择： 行和单元格选择模式
• 节点功能： 复选框、按需加载、展开／折叠
• 行操作： 拖放、合并单元格
• 数据操作： 剪贴板操作、导出到 Excel
• 样式设置： 条件样式、自定义模板
• 高级功能： 上下文菜单、工具提示、支持 MVVM

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 创建 WinUI TreeGrid 应用程序
• 安装 NuGet 包（Syncfusion.Grid.WinUI）
• 导入命名空间并进行基本初始化
• 使用最精简的 XAML/C# 代码创建第一个 TreeGrid
• 快速验证渲染结果

数据绑定

📄 阅读： references/data-binding.md

• 绑定自关联数据（ParentPropertyName、ChildPropertyName）
• 配置根节点的 SelfRelationRootValue
• 绑定嵌套集合（分层对象）
• 创建数据模型和 ViewModel
• ItemsSource 绑定模式
• 树结构构建示例

列与列类型

📄 阅读： references/columns.md

• 8 种内置列类型（文本、数值、日期、时间、复选框、组合框、超链接、模板）
• 自动生成列与手动定义列
• 用于自定义的 AutoGeneratingColumn 事件
• 根据数据类型选择列类型
• TreeGridColumn 基类及其属性

列配置

📄 阅读： references/column-configuration.md

• 列大小和宽度模式（Auto、Star、Fill）
• 标题自定义和格式设置
• 用于数据绑定的 MappingName
• 列可见性和排序
• 用于固定显示的冻结列
• 单元格和编辑模板

编辑与验证

📄 阅读： references/editing.md

• 启用编辑（AllowEditing 属性）
• 控制列级别的编辑
• 编辑模式配置
• CurrentCellBeginEdit 和 CurrentCellEndEdit 事件
• 编辑过程中的数据验证
• 以编程方式执行编辑操作
• 自定义编辑器模板

选择

📄 阅读： references/selection.md

• 选择模式（Single、Multiple、Extended、None）
• 行选择与单元格选择（SelectionUnit）
• SelectionChanging 和 SelectionChanged 事件
• 以编程方式选择的 API
• SelectedItem、SelectedItems 属性
• 键盘导航模式

排序和筛选

📄 阅读： references/sorting-filtering.md

• 单列和多列排序
• SortColumnDescriptions 集合
• SortColumnChanging/Changed 事件
• 自定义排序逻辑
• 受 Excel 启发的筛选 UI（AllowFiltering）
• FilterChanging/Changed 事件
• 使用谓词进行程序化筛选
• 筛选自定义

行操作

📄 阅读： references/row-operations.md

• 自定义行高
• 行拖放功能
• 拖放事件和验证
• 合并单元格功能
• 单元格合并配置
• 条件行样式
• 行验证规则

节点功能

📄 阅读： references/node-features.md

• 用于选择的节点复选框
• 递归勾选行为
• NodeCheckStateChanging/Changed 事件
• 按需加载（延迟加载子节点）
• LoadOnDemandCommand
• HasChildNodes 属性
• 动态填充子节点

数据操作

📄 阅读： references/data-operations.md

• 剪贴板操作（复制/粘贴）
• CopyOption 属性配置
• CopyGridCellContent 事件
• 导出到 Excel 功能
• ExcelExportingOptions
• 导出所选项
• 导出自定义和格式设置

样式和自定义

📄 阅读： references/styling-customization.md

• 基于数据的条件样式
• 单元格和行样式
• QueryCellStyle 和 QueryRowStyle 事件
• GridLines 自定义
• GridLinesVisibility 属性
• UI 自定义和模板
• 主题集成

高级功能

📄 阅读： references/advanced-features.md

• 上下文浮出菜单
• 自定义上下文菜单项
• 单元格和标题的工具提示
• 自定义工具提示模板
• 支持 MVVM 模式
• 命令和数据绑定
• 辅助方法和实用工具
• 性能优化技术

快速入门示例

自关联数据

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

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

嵌套集合数据

public class PersonInfo
{
    public string FirstName { get; set; }
    public string LastName { get; set; }
    public double Salary { get; set; }
    public ObservableCollection<PersonInfo> Children { get; set; }
}

<treeGrid:SfTreeGrid x:Name="treeGrid"
                    ItemsSource="{Binding PersonDetails}"
                    ChildPropertyName="Children" />

常见模式

自关联数据结构

当数据对象通过 ID/ParentID 相互引用时使用：

// Each employee has an ID and ReportsTo (parent ID)
ParentPropertyName = "ID"
ChildPropertyName = "ReportsTo"
SelfRelationRootValue = -1  // Root nodes have ReportsTo = -1

嵌套集合结构

当数据对象包含子集合时使用：

// Each person has a Children property containing child objects
ChildPropertyName = "Children"
// No ParentPropertyName needed

列自动生成控制

<treeGrid:SfTreeGrid AutoGenerateColumns="True" />


<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 数据绑定

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

展开/折叠控制

// 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();

关键属性

数据绑定属性

• ItemsSource - 数据源（IEnumerable）

  • 适用情况：数据绑定时始终必需
  • 原因：提供要显示的数据

• ChildPropertyName - 包含子集合或父级引用的属性

  • 适用情况：所有树结构均必需
  • 原因：定义树关系

• ParentPropertyName - 包含唯一标识符的属性（仅自关联数据）

  • 适用情况：仅用于自关联数据
  • 原因：标识父节点

• SelfRelationRootValue - 表示根节点的值（仅自关联数据）

  • 适用情况：用于自关联数据时
  • 原因：标识哪些节点为根节点（默认值：null）

显示属性

• AutoGenerateColumns - 根据属性自动创建列（默认值：true）

  • 适用情况：设为 false 以手动控制列
  • 原因：自动定义列或显式定义列

• AutoExpandMode - 初始展开状态

  • 适用情况：控制树的初始可见性
  • 原因：提升用户探索数据的体验

• ColumnWidthMode - 列宽的计算方式

  • 适用情况：控制列宽调整行为
  • 原因：自动、星号或固定宽度

功能属性

• AllowEditing - 启用单元格编辑（默认：false）

  • 适用场景：需要可编辑的网格
  • 原因：可就地修改数据

• AllowFiltering - 启用筛选界面（默认：false）

  • 适用场景：需要筛选大型数据集
  • 原因：支持类似 Excel 的数据筛选

• SelectionMode - 行/单元格选择类型

  • 适用场景：控制选择行为
  • 原因：单选、多选、扩展选择或不选择

• SelectionUnit - 选择行或单元格

  • 适用场景：定义选择粒度
  • 原因：按行或按单元格选择

常见用例

组织层级结构

显示公司架构以及员工向经理汇报的关系：

ParentPropertyName = "EmployeeID"
ChildPropertyName = "ManagerID"

文件系统浏览器

以树形结构显示文件夹和文件：

ChildPropertyName = "SubItems"  // Nested collection

类别管理

显示产品类别及其子类别：

ChildPropertyName = "SubCategories"

物料清单（BOM）

显示产品装配结构及组件：

ParentPropertyName = "PartID"
ChildPropertyName = "ParentPartID"

任务/项目管理

显示任务及其子任务：

ChildPropertyName = "SubTasks"

地理层级结构

显示国家 > 州 > 城市：

ChildPropertyName = "Children"

故障排除

未能形成树形结构

• 确认 ParentPropertyName 和 ChildPropertyName 设置正确
• 检查 SelfRelationRootValue 是否与数据中的根节点标识匹配
• 确保数据关系定义正确

未显示列

• 将 AutoGenerateColumns 设为 True，或手动定义列
• 检查 MappingName 是否与属性名称完全匹配（区分大小写）
• 确认数据源已绑定到 ItemsSource

大型数据集的性能问题

• 启用按需加载，以实现延迟加载
• 使用按需模式，延迟加载子节点
• 对于超大型树结构，可考虑使用数据虚拟化

无法编辑

• 在 TreeGrid 上将 AllowEditing 设为 True
• 检查列级别的 AllowEditing 属性
• 确保数据对象实现了 INotifyPropertyChanged

---

**后续步骤：**阅读入门指南，然后根据需求查看特定功能的参考文档。