syncfusion-wpf-treeview

实现 Syncfusion WPF TreeView（SfTreeView）

Syncfusion WPF TreeView（SfTreeView）是一款功能强大的数据导向控件，可在树形结构中显示分层数据，并支持展开和折叠节点。它常用于在 WPF 应用程序中显示文件夹结构、组织架构、类别树和嵌套关系。

何时使用此技能

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

• 以树形结构显示分层数据（文件夹、类别、组织架构图）
• 实现可展开和可折叠的节点，并建立父子关系
• 启用树形结构中的选择功能（单选或多选）
• 为树节点添加复选框功能，并递归管理状态
• 支持拖放，以重新排序或整理树项
• 启用树节点内容的内联编辑
• 按需加载数据，以处理大型分层数据集
• 将集合中的数据绑定到 TreeView（绑定或非绑定模式）
• 使用模板、主题和视觉样式自定义外观
• 显示树线，以直观呈现层次关系
• 动态执行树数据的 CRUD 操作

此技能提供关于所有 TreeView 功能的全面指导，从基础设置到高级自定义。

组件概览

主要功能：

• **数据绑定模式：**绑定（数据源）和非绑定（手动添加节点）
• **选择：**支持单选、多选、扩展选择及键盘导航
• **复选框：**单独或递归管理状态
• **拖放：**在 TreeView 内部或拖放到其他控件
• **编辑：**使用模板和验证进行内联编辑
• **按需加载：**通过延迟加载提升大型数据集的性能
• **自定义：**支持全面自定义项、展开器和编辑模板
• **树线：**用于显示层次结构的视觉指示线
• **性能：**优化的视图复用和扁平渲染架构

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集部署
• NuGet 包设置（Syncfusion.SfTreeView.WPF）
• 必需的程序集引用
• 命名空间导入（XAML 和 C#）
• 在 XAML 中创建基础 TreeView
• 以编程方式创建 TreeView
• 许可证配置

数据填充

📄 阅读： references/data-population.md

• 非绑定模式（TreeViewNode 对象）
• 绑定模式（分层数据源绑定）
• 用于嵌套集合的 ChildPropertyName
• 用于复杂层次结构的 HierarchyPropertyDescriptors
• ItemTemplate 配置
• ItemsSource 绑定模式
• 使用 MVVM 进行数据绑定

选择

📄 阅读： references/selection.md

• 选择模式（None、Single、SingleDeselect、Multiple、Extended）
• 使用鼠标和键盘进行 UI 选择
• 以编程方式选择（SelectedItem、SelectedItems）
• 将选择状态绑定到数据模型
• 选择事件（SelectionChanging、SelectionChanged）
• CurrentItem 属性
• 键盘导航

复选框

📄 阅读： references/checkboxes.md

• 为树项添加复选框
• CheckBoxMode（None、Default、Recursive）
• CheckedItems 集合绑定
• 复选框状态的递归传播
• 以编程方式勾选或取消勾选
• ItemTemplateDataContextType 配置
• 绑定和非绑定模式下的复选框

编辑

📄 阅读： references/editing.md

• 启用编辑（AllowEditing 属性）
• 编辑触发方式（F2 键、单击、双击）
• EditTemplate 和 EditTemplateSelector
• 以编程方式编辑（BeginEdit、EndEdit）
• 编辑事件和验证
• 提交和还原更改
• 绑定和非绑定模式下的编辑模式

拖放

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

• 启用拖放（AllowDragging）
• 拖动多个选中项
• 放置位置指示器
• 拖放事件（ItemDragStarting、ItemDragOver、ItemDropping、ItemDropped）
• 在多个 TreeView 之间拖动
• 拖动到其他控件（ListView、DataGrid）
• 自定义拖动行为

树结构功能

📄 阅读： references/tree-structure.md

• 展开和折叠节点
• AutoExpandMode 属性
• ExpandActionTrigger（Node、Expander）
• 按需加载，实现延迟加载
• 树线可视化（ShowLines 属性）
• 自定义展开器模板
• 通过编程方式展开/折叠
• ExpanderTemplate

外观和自定义

📄 阅读： references/appearance.md

• 自定义项高度
• ItemTemplate 和 ItemTemplateSelector
• 视觉状态和样式
• 使用 SfSkinManager 设置主题
• 自定义展开器图标
• 控制缩进和间距
• 自定义边框和背景
• FullRowSelect 属性

CRUD 操作

📄 阅读： references/crud-operations.md

• 通过编程方式添加节点
• 从 TreeView 中移除节点
• 更新节点内容
• 绑定模式与非绑定模式下的 CRUD 操作
• 刷新数据和 UI 更新
• 集合更改处理

快速入门示例

基本非绑定 TreeView

<Window 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"
        xmlns:Engine="clr-namespace:Syncfusion.UI.Xaml.TreeView.Engine;assembly=Syncfusion.SfTreeView.WPF">
    <Grid>
        <syncfusion:SfTreeView x:Name="treeView" Width="300">
            <syncfusion:SfTreeView.Nodes>
                <Engine:TreeViewNode Content="Documents" IsExpanded="True">
                    <Engine:TreeViewNode.ChildNodes>
                        <Engine:TreeViewNode Content="Reports"/>
                        <Engine:TreeViewNode Content="Invoices"/>
                    </Engine:TreeViewNode.ChildNodes>
                </Engine:TreeViewNode>
                <Engine:TreeViewNode Content="Pictures" IsExpanded="True">
                    <Engine:TreeViewNode.ChildNodes>
                        <Engine:TreeViewNode Content="Vacation"/>
                        <Engine:TreeViewNode Content="Family"/>
                    </Engine:TreeViewNode.ChildNodes>
                </Engine:TreeViewNode>
            </syncfusion:SfTreeView.Nodes>
        </syncfusion:SfTreeView>
    </Grid>
</Window>

基本绑定 TreeView

<syncfusion:SfTreeView x:Name="treeView"
                       ItemsSource="{Binding Folders}"
                       ChildPropertyName="SubFolders"
                       AutoExpandMode="RootNodes">
    <syncfusion:SfTreeView.ItemTemplate>
        <DataTemplate>
            <TextBlock Text="{Binding FolderName}" 
                       VerticalAlignment="Center"/>
        </DataTemplate>
    </syncfusion:SfTreeView.ItemTemplate>
</syncfusion:SfTreeView>

// ViewModel
public class ViewModel : INotifyPropertyChanged
{
    public ObservableCollection<Folder> Folders { get; set; }
    
    public ViewModel()
    {
        Folders = new ObservableCollection<Folder>
        {
            new Folder 
            { 
                FolderName = "Documents",
                SubFolders = new ObservableCollection<Folder>
                {
                    new Folder { FolderName = "Reports" },
                    new Folder { FolderName = "Invoices" }
                }
            }
        };
    }
}

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

常见模式

带选择和复选框的 TreeView

<syncfusion:SfTreeView x:Name="treeView"
                       ItemsSource="{Binding Items}"
                       ChildPropertyName="Children"
                       SelectionMode="Multiple"
                       CheckBoxMode="Recursive"
                       CheckedItems="{Binding CheckedItems}"
                       ItemTemplateDataContextType="Node">
    <syncfusion:SfTreeView.ItemTemplate>
        <DataTemplate>
            <Grid>
                <CheckBox IsChecked="{Binding IsChecked, Mode=TwoWay}" 
                          FocusVisualStyle="{x:Null}"/>
                <TextBlock Text="{Binding Content.Name}" 
                           Margin="25,0,0,0" 
                           VerticalAlignment="Center"/>
            </Grid>
        </DataTemplate>
    </syncfusion:SfTreeView.ItemTemplate>
</syncfusion:SfTreeView>

按需加载的 TreeView

<syncfusion:SfTreeView x:Name="treeView"
                       ItemsSource="{Binding Items}"
                       ChildPropertyName="Children"
                       LoadOnDemandCommand="{Binding LoadOnDemandCommand}"/>

public class TreeViewViewModel
{
    public ICommand LoadOnDemandCommand { get; }

    public TreeViewViewModel()
    {
        LoadOnDemandCommand = new RelayCommand(LoadChildren);
    }

    private void LoadChildren(object param)
    {
        var node = param as TreeViewNode;

        if (node.ChildNodes.Count == 0)
        {
            node.PopulateChildNodes(new List<MyModel>
            {
                new MyModel { Name = "Child 1" },
                new MyModel { Name = "Child 2" }
            });

            node.IsExpanded = true;
        }
    }
}

public class MyModel
{
    public string Name { get; set; }

    // Used for hierarchical binding (important for TreeView)
    public List<MyModel> Children { get; set; }
}

支持拖放的 TreeView

<syncfusion:SfTreeView x:Name="treeView"
                       ItemsSource="{Binding Items}"
                       ChildPropertyName="Children"
                       AllowDragging="True"
                       SelectionMode="Multiple"
                       ItemDropping="TreeView_ItemDropping"/>

private void TreeView_ItemDropping(object sender, TreeViewItemDroppingEventArgs e)
{
    // Validate drop operation
    if (!IsValidDrop(e.TargetNode, e.DraggingNodes))
    {
        e.Handled = true; // Cancel drop
    }
}

关键属性

属性	类型	描述
ItemsSource	IEnumerable	绑定模式的数据源
ChildPropertyName	string	子集合的属性名称
SelectionMode	SelectionMode	Single、Multiple、Extended 等
SelectedItem	object	当前选中项
SelectedItems	ObservableCollection	多个选中项
CheckBoxMode	CheckBoxMode	None、Default、Recursive
CheckedItems	ObservableCollection	已勾选项集合
AllowDragging	bool	启用拖放
AllowEditing	bool	启用内联编辑
AutoExpandMode	AutoExpandMode	AllNodes、RootNodes、None
ExpandActionTrigger	ExpandActionTrigger	单击 Node 或 Expander
ShowLines	bool	显示树线
ItemTemplate	DataTemplate	项显示模板
EditTemplate	DataTemplate	编辑模式模板
ExpanderTemplate	DataTemplate	展开器图标模板

常见用例

文件资源管理器

使用图标显示文件夹和文件层级结构，让用户能够通过拖放浏览、选择和管理文件。

组织结构图

显示包含员工节点的公司层级结构，支持选择和展开，以查看团队结构。

类别管理

通过复选框显示产品类别，支持多选，以便对类别树执行批量操作。

项目结构

显示项目文件和文件夹；对于大型项目，支持按需加载，并支持内联编辑文件名。

设置/首选项树

显示嵌套的配置选项，并通过复选框按层级启用或禁用功能。

菜单/导航树

创建带可展开分区和可视化树线的分层导航菜单。

---

后续步骤： 根据要实现的功能，查阅上方对应的参考文档。先阅读 getting-started.md 完成初始设置，然后按需探索其他功能。