syncfusion-winui-treeview

实现 WinUI TreeView

在 Windows App SDK 应用程序中实现 Syncfusion® WinUI TreeView（SfTreeView）控件以显示分层数据的综合指南。

何时使用此技能

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

• 以树形结构显示分层数据（文件、文件夹、类别）
• 在 WinUI 应用程序中实现文件资源管理器或文件夹浏览器
• 创建组织结构图或汇报关系结构
• 构建类别导航，支持展开和折叠节点
• 启用节点选择，支持单选或多选模式
• 支持内联编辑树节点
• 实现拖放操作，用于重新排序或移动节点
• 按需加载数据，以处理大型层级结构
• 使用模板和样式自定义树的外观
• 处理分层数据的 CRUD 操作

TreeView 控件非常适合可视化父子关系和嵌套数据结构。

组件概览

SfTreeView 是一种面向数据的控件，可通过展开和折叠节点以分层结构显示数据。它通常用于展示文件夹结构、组织层级或嵌套关系。

主要功能

• 双数据模式： 绑定模式（数据绑定）和非绑定模式（手动添加节点）
• 灵活选择： 多种选择模式，包括支持键盘修饰键的 Extended 模式
• 内联编辑： 使用自定义模板编辑节点内容
• 拖放操作： 在树中重新排序或移动节点
• 按需加载： 父节点展开时延迟加载子节点
• 复选框： 内置复选框支持多选
• 上下文菜单： 添加浮出菜单以执行节点操作
• 动画： 流畅的展开/折叠动画
• MVVM 支持： 完整支持命令和数据绑定
• 自定义： 使用模板全面控制外观

何时选择 TreeView

在以下情况下选择 TreeView：

• 需要对父子数据进行分层可视化
• 需要可展开/可折叠的部分，以节省显示空间
• 需要多个嵌套层级（深度为 2 级或以上）
• 需要使用用户熟悉的树形导航模式

以下情况可考虑其他方案：

• 平面列表 → 使用 ListView 或 DataGrid
• 简单的分组数据 → 使用带分组功能的 ListView
• 网络/图关系 → 使用自定义可视化

文档与导航指南

入门

📄 阅读： references/getting-started.md

从这里开始，完成初始设置并创建第一个 TreeView：

• 安装 NuGet 包（Syncfusion.TreeView.WinUI）
• 将 TreeView 添加到 XAML 页面
• 使用非绑定节点实现基本 TreeView
• 使用分层数据的简单绑定模式示例
• 命名空间导入和控件初始化
• 项目配置

数据管理

📄 阅读： references/data-binding.md

了解如何将 TreeView 绑定到数据模型：

• 绑定模式与非绑定模式对比
• 使用 ItemsSource 绑定分层数据源
• 用于自关联绑定的 ChildPropertyName
• 用于复杂层级结构的 HierarchyPropertyDescriptors
• ItemTemplate 和 ExpanderTemplate 配置
• ObservableCollection 和 INotifyPropertyChanged
• NodePopulationMode（OnDemand 与 Instant）
• 用于变更跟踪的 NotificationSubscriptionMode

📄 阅读： references/drag-drop-crud.md

掌握节点操作和 CRUD 操作：

• 启用拖放（AllowDragging、AllowDrop）
• 拖放事件和自定义
• 以编程方式添加节点
• 从层级结构中删除节点
• 更新节点内容
• 按需加载实现
• 上下文菜单操作

用户交互功能

📄 阅读： references/selection.md

实现节点选择功能：

• SelectionMode 选项（None、Single、SingleDeselect、Multiple、Extended）
• 使用鼠标和触控进行 UI 选择
• 以编程方式选择（SelectedItem、SelectedItems）
• 选择事件（SelectionChanging、SelectionChanged）
• 使用键盘导航进行选择
• 使用 Ctrl/Shift 修饰键进行多选
• 自定义选择行为和样式

📄 阅读： references/expand-collapse.md

控制节点的展开和折叠：

• AutoExpandMode 选项
• 以编程方式展开和折叠
• 配置 ExpandAction（单击/双击）
• 使用 IsExpanded 属性
• 展开/折叠事件
• 全部展开和全部折叠场景
• 保持展开状态

📄 阅读： references/editing.md

启用树节点的内联编辑：

• 使用 AllowEditing 启用编辑
• EditTemplate 和 EditTemplateSelector
• 启动编辑模式（F2 键）
• 提交和取消编辑
• 编辑事件（ItemBeginEdit、ItemEndEdit）
• 编辑期间的验证
• 绑定模式与非绑定模式下编辑的区别

📄 阅读： references/interactivity.md

为 TreeView 添加交互功能：

• 复选框支持和配置
• 上下文浮出菜单
• 交互事件（ItemTapped、ItemDoubleTapped、ItemHolding）
• 键盘快捷键和导航
• 触控手势
• 滚动行为
• 动画设置（IsAnimationEnabled）

高级功能

📄 阅读： references/mvvm-patterns.md

使用 TreeView 实现 MVVM 架构：

• 层次结构数据的 MVVM 模式
• TreeView 中的命令
• 数据绑定最佳实践
• 树形结构的 ViewModel 设计
• 处理 ObservableCollections
• 将事件转换为命令
• 对 TreeView ViewModel 进行单元测试

自定义

📄 阅读： references/appearance-customization.md

自定义视觉外观：

• 用于节点内容的 ItemTemplate
• 用于展开/折叠图标的 ExpanderTemplate
• 自定义项目高度（ItemHeight、QueryNodeSize）
• TreeLines 配置
• 缩进和间距
• 添加图标和图片
• 设置选中/悬停状态的样式
• 主题集成

快速入门示例

以下是一个展示文件结构的简易 TreeView：

XAML：

<Page xmlns:treeView="using:Syncfusion.UI.Xaml.TreeView">
    
    <Page.DataContext>
        <local:FileViewModel />
    </Page.DataContext>
    
    <treeView:SfTreeView x:Name="treeView"
                          Width="400"
                          Height="500"
                          ChildPropertyName="SubFiles"
                          ItemsSource="{Binding Files}">
        <treeView:SfTreeView.ItemTemplate>
            <DataTemplate>
                <StackPanel Orientation="Horizontal">
                    <TextBlock Text="📁" Margin="0,0,5,0" />
                    <TextBlock Text="{Binding FileName}" 
                               VerticalAlignment="Center" />
                </StackPanel>
            </DataTemplate>
        </treeView:SfTreeView.ItemTemplate>
    </treeView:SfTreeView>
    
</Page>

ViewModel（C#）：

public class FileViewModel : INotifyPropertyChanged
{
    public ObservableCollection<FileNode> Files { get; set; }
    
    public FileViewModel()
    {
        Files = new ObservableCollection<FileNode>
        {
            new FileNode 
            { 
                FileName = "Documents",
                SubFiles = new ObservableCollection<FileNode>
                {
                    new FileNode { FileName = "Resume.docx" },
                    new FileNode { FileName = "CoverLetter.pdf" }
                }
            },
            new FileNode 
            { 
                FileName = "Downloads",
                SubFiles = new ObservableCollection<FileNode>()
            }
        };
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
}

public class FileNode : INotifyPropertyChanged
{
    private string _fileName;
    private ObservableCollection<FileNode> _subFiles;
    
    public string FileName
    {
        get => _fileName;
        set { _fileName = value; OnPropertyChanged(); }
    }
    
    public ObservableCollection<FileNode> SubFiles
    {
        get => _subFiles;
        set { _subFiles = value; OnPropertyChanged(); }
    }
    
    public event PropertyChangedEventHandler PropertyChanged;
    
    protected void OnPropertyChanged([CallerMemberName] string name = null)
    {
        PropertyChanged?.Invoke(this, new PropertyChangedEventArgs(name));
    }
}

常见模式

模式 1：带图标的文件资源管理器

<treeView:SfTreeView ItemsSource="{Binding Items}"
                      ChildPropertyName="Children">
    <treeView:SfTreeView.ItemTemplate>
        <DataTemplate>
            <StackPanel Orientation="Horizontal">
                <FontIcon Glyph="{Binding Icon}" 
                          FontSize="16" 
                          Margin="0,0,8,0" />
                <TextBlock Text="{Binding Name}" />
            </StackPanel>
        </DataTemplate>
    </treeView:SfTreeView.ItemTemplate>
</treeView:SfTreeView>

模式 2：使用复选框进行多选

<treeView:SfTreeView SelectionMode="Multiple"
                      CheckBoxMode="Recursive">
    
</treeView:SfTreeView>

模式 3：按需加载

<treeView:SfTreeView LoadOnDemandCommand="{Binding LoadChildrenCommand}">
    
</treeView:SfTreeView>

模式 4：以编程方式选择

// Single selection
treeView.SelectedItem = viewModel.RootNode.Children[0];

// Multiple selection
treeView.SelectedItems.Add(node1);
treeView.SelectedItems.Add(node2);

// Select all nodes
treeView.SelectAll();

模式 5：上下文菜单操作

<treeView:SfTreeView ItemHolding="OnItemHolding">
    
</treeView:SfTreeView>

private void OnItemHolding(object sender, ItemHoldingEventArgs e)
{
    var flyout = new MenuFlyout();
    flyout.Items.Add(new MenuFlyoutItem { Text = "Rename" });
    flyout.Items.Add(new MenuFlyoutItem { Text = "Delete" });
    flyout.ShowAt(e.Element);
}

关键属性和方法

基本属性

属性	类型	描述
ItemsSource	object	要绑定的层次结构数据集合
ChildPropertyName	string	包含子项的属性名称
SelectionMode	SelectionMode	选择行为（None、Single、Multiple、Extended）
SelectedItem	object	当前选中的项目
SelectedItems	ObservableCollection	选中项目的集合
AllowEditing	bool	启用内联编辑
AllowDragging	bool	启用拖放
AutoExpandMode	AutoExpandMode	自动展开行为（None、AllNodes、RootNodes）
IsAnimationEnabled	bool	启用展开/折叠动画
CheckBoxMode	CheckBoxMode	复选框行为（None、Recursive）
LoadOnDemand	bool	启用子节点的延迟加载

主要方法

方法	描述
ExpandAll()	展开树中的所有节点
CollapseAll()	折叠所有节点
ExpandNode(TreeViewNode)	展开指定节点
CollapseNode(TreeViewNode)	折叠指定节点
SelectAll()	选择所有节点
ClearSelection()	清除所有选择
BringIntoView(TreeViewNode)	滚动以显示节点

重要事件

事件	描述
SelectionChanged	选择发生更改时触发
ItemTapped	点击节点时触发
ItemDoubleTapped	双击节点时触发
NodeExpanding	节点展开前触发
NodeExpanded	节点展开后触发
NodeCollapsing	节点折叠前触发
NodeCollapsed	节点折叠后触发
ItemBeginEdit	开始编辑时触发
ItemEndEdit	结束编辑时触发

常见用例

用例 1：文件系统浏览器

显示电脑上的文件夹和文件，支持展开/折叠、文件图标和上下文菜单操作（重命名、删除、复制）。

适用场景： 文档管理、文件选择器、资源浏览器

所需的主要功能：

• 使用分层数据的绑定模式
• 带图标的自定义 ItemTemplate
• 上下文浮出菜单
• 通过拖放移动文件

用例 2：组织结构图

展示包含部门、团队和员工的公司层级结构，并支持通过选择查看详细信息。

适用场景： 人力资源应用、组织结构可视化、汇报关系结构

所需的主要功能：

• 使用员工数据的绑定模式
• 使用 AutoExpandMode 控制初始显示
• 单选模式
• 用于员工卡片的自定义模板

用例 3：产品类别浏览器

用于电子商务的类别导航，支持展开类别和子类别。

适用场景： 电子商务、内容管理、产品目录

所需的主要功能：

• 为大型目录按需加载
• 单选
• 自定义类别样式
• 用于导航的点击事件

用例 4：设置面板

具有分组选项和可展开分区的分层设置界面。

适用场景： 应用设置、偏好设置 UI、配置面板

所需的主要功能：

• 使用手动节点的非绑定模式
• 使用 AutoExpandMode 提高便利性
• 用于设置控件的自定义 ItemTemplate
• 保持展开状态

用例 5：项目资源管理器（类似 IDE）

显示与 Visual Studio 类似的解决方案结构，其中包含项目、文件夹和文件。

适用场景： 开发者工具、IDE、代码编辑器

所需的主要功能：

• 使用解决方案模型的绑定模式
• 支持内联编辑和重命名
• 通过拖放重新组织
• 用于文件操作的上下文菜单
• 支持批量操作的多选

性能提示

• 对于大型层级结构（1000 个以上节点），使用 OnDemand NodePopulationMode
• 仅在需要时将 NotificationSubscriptionMode 设为 CollectionChanged
• 使用 x:Bind 代替 Binding，以获得更好的性能
• 尽量降低 ItemTemplate 的复杂度
• 对于包含大量子项的深层级结构，使用 LoadOnDemand
• 对于非常大的平面区段，考虑使用虚拟化

故障排除速查表

问题	解决方案
节点无法展开	检查 ChildPropertyName 是否与属性名称完全匹配
选择不起作用	将 SelectionMode 设为 Single 或 Multiple
数据未更新	在数据模型上实现 INotifyPropertyChanged
子项未加载	将 NotificationSubscriptionMode 设为 CollectionChanged
性能不佳	启用 OnDemand 模式和 LoadOnDemand
未启用编辑	将 AllowEditing="True" 并定义 EditTemplate
拖放不起作用	将 AllowDragging 和 AllowDrop 都设为 true

相关组件

• ListView - 用于不带层级结构的扁平列表
• DataGrid - 用于支持层级结构的表格数据（TreeGrid）
• Expander - 用于简单的展开/折叠区块

---

后续步骤： 根据具体需求阅读上方链接的参考文档。如果你刚接触 TreeView，请从 getting-started.md 开始。