syncfusion-wpf-treeview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion WPF TreeView (SfTreeView)

实现Syncfusion WPF TreeView（SfTreeView）

The Syncfusion WPF TreeView (SfTreeView) is a powerful data-oriented control for displaying hierarchical data in a tree structure with expanding and collapsing nodes. It's commonly used to display folder structures, organizational hierarchies, category trees, and nested relationships in WPF applications.

Syncfusion WPF TreeView（SfTreeView）是一个功能强大的面向数据的控件，用于在树形结构中展示层级数据，支持节点的展开与折叠。它通常用于在WPF应用中展示文件夹结构、组织层级、分类树以及嵌套关系。

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Display hierarchical data in a tree structure (folders, categories, org charts)
Implement expandable/collapsible nodes with parent-child relationships
Enable selection in tree structures (single or multiple items)
Add checkbox functionality to tree nodes with recursive state management
Support drag-and-drop for reordering or reorganizing tree items
Enable inline editing of tree node content
Load data on demand for large hierarchical datasets
Bind data to TreeView from collections (bound or unbound modes)
Customize appearance with templates, themes, and visual styles
Display tree lines to visualize hierarchical relationships
Perform CRUD operations on tree data dynamically

This skill provides comprehensive guidance for all TreeView features, from basic setup to advanced customization.

当你需要以下功能时，可以使用该技能：

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

该技能提供了从基础设置到高级定制的所有TreeView功能的全面指导。

Component Overview

组件概述

Key Capabilities:

Data Binding Modes: Bound (data source) and Unbound (manual nodes)
Selection: Single, Multiple, Extended with keyboard navigation
Checkboxes: Individual or recursive state management
Drag & Drop: Within TreeView or to other controls
Editing: Inline editing with templates and validation
Load on Demand: Lazy loading for performance with large datasets
Customization: Full template support for items, expanders, and editing
Tree Lines: Visual indicators for hierarchical structure
Performance: Optimized view reuse and flat rendering architecture

核心功能：

数据绑定模式：绑定模式（数据源）和非绑定模式（手动节点）
选择功能：单选、多选、扩展选择，支持键盘导航
复选框：独立或递归状态管理
拖放：在TreeView内部或与其他控件之间进行拖放
编辑：内联编辑，支持模板和验证
按需加载：懒加载，提升大型数据集的性能
定制化：全面支持项、展开器和编辑的模板定制
树形连线：层级结构的可视化指示器
性能：优化的视图复用和平铺渲染架构

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md

Installation and assembly deployment
NuGet package setup (Syncfusion.SfTreeView.WPF)
Required assembly references
Namespace imports (XAML and C#)
Creating basic TreeView in XAML
Creating TreeView programmatically
License configuration

📄 阅读： references/getting-started.md

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

Data Population

数据填充

📄 Read: references/data-population.md

Unbound mode (TreeViewNode objects)
Bound mode (hierarchical data source binding)
ChildPropertyName for nested collections
HierarchyPropertyDescriptors for complex hierarchies
ItemTemplate configuration
ItemsSource binding patterns
Data binding with MVVM

📄 阅读： references/data-population.md

非绑定模式（TreeViewNode对象）
绑定模式（层级数据源绑定）
用于嵌套集合的ChildPropertyName
用于复杂层级的HierarchyPropertyDescriptors
ItemTemplate配置
ItemsSource绑定模式
结合MVVM的数据绑定

Selection

选择功能

📄 Read: references/selection.md

Selection modes (None, Single, SingleDeselect, Multiple, Extended)
UI selection with mouse and keyboard
Programmatic selection (SelectedItem, SelectedItems)
Binding selection state to data model
Selection events (SelectionChanging, SelectionChanged)
CurrentItem property
Keyboard navigation

📄 阅读： references/selection.md

选择模式（无、单选、单选可取消、多选、扩展选择）
鼠标和键盘的UI选择操作
编程式选择（SelectedItem、SelectedItems）
将选择状态绑定到数据模型
选择事件（SelectionChanging、SelectionChanged）
CurrentItem属性
键盘导航

Checkboxes

复选框

📄 Read: references/checkboxes.md

Adding checkboxes to tree items
CheckBoxMode (None, Default, Recursive)
CheckedItems collection binding
Recursive checkbox state propagation
Programmatic check/uncheck
ItemTemplateDataContextType configuration
Checkbox in bound and unbound modes

📄 阅读： references/checkboxes.md

为树形项添加复选框
CheckBoxMode（无、默认、递归）
CheckedItems集合绑定
递归复选框状态传播
编程式勾选/取消勾选
ItemTemplateDataContextType配置
绑定和非绑定模式下的复选框

Editing

编辑功能

📄 Read: references/editing.md

Enabling editing (AllowEditing property)
Edit triggers (F2 key, single click, double click)
EditTemplate and EditTemplateSelector
Programmatic editing (BeginEdit, EndEdit)
Editing events and validation
Committing and reverting changes
Edit mode in bound and unbound modes

📄 阅读： references/editing.md

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

Drag and Drop

拖放功能

📄 Read: references/drag-and-drop.md

Enabling drag and drop (AllowDragging)
Dragging multiple selected items
Drop position indicators
Drag and drop events (ItemDragStarting, ItemDragOver, ItemDropping, ItemDropped)
Dragging between TreeViews
Drag to other controls (ListView, DataGrid)
Customizing drag behavior

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

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

Tree Structure Features

树形结构功能

📄 Read: references/tree-structure.md

Expanding and collapsing nodes
AutoExpandMode property
ExpandActionTrigger (Node, Expander)
Load on demand for lazy loading
Tree lines visualization (ShowLines property)
Expander template customization
Programmatic expand/collapse
ExpanderTemplate

📄 阅读： references/tree-structure.md

展开和折叠节点
AutoExpandMode属性
ExpandActionTrigger（节点、展开器）
用于懒加载的按需加载
树形连线可视化（ShowLines属性）
展开器模板定制
编程式展开/折叠
ExpanderTemplate

Appearance and Customization

外观与定制化

📄 Read: references/appearance.md

Item height customization
ItemTemplate and ItemTemplateSelector
Visual states and styling
Theming with SfSkinManager
Custom expander icons
Indentation and spacing control
Border and background customization
FullRowSelect property

📄 阅读： references/appearance.md

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

CRUD Operations

CRUD操作

📄 Read: references/crud-operations.md

Adding nodes programmatically
Removing nodes from TreeView
Updating node content
CRUD in bound vs unbound mode
Refreshing data and UI updates
Collection change handling

📄 阅读： references/crud-operations.md

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

Quick Start Example

快速入门示例

Basic Unbound TreeView

基础非绑定TreeView

xml

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

xml

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

Basic Bound TreeView

基础绑定TreeView

xml

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

csharp

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

xml

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

csharp

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

Common Patterns

常见模式

TreeView with Selection and Checkboxes

带选择和复选框的TreeView

xml

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

xml

<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 with Load on Demand

带按需加载的TreeView

xml

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

csharp

private void TreeView_LoadOnDemand(object sender, LoadOnDemandEventArgs e)
{
    var node = e.Node;
    var model = node.Content as MyModel;
    
    // Load child items asynchronously
    var childItems = LoadChildItemsFromDatabase(model.Id);
    node.PopulateChildNodes(childItems);
    
    e.HasChildNodes = childItems.Count > 0;
}

xml

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

csharp

private void TreeView_LoadOnDemand(object sender, LoadOnDemandEventArgs e)
{
    var node = e.Node;
    var model = node.Content as MyModel;
    
    // 异步加载子项
    var childItems = LoadChildItemsFromDatabase(model.Id);
    node.PopulateChildNodes(childItems);
    
    e.HasChildNodes = childItems.Count > 0;
}

TreeView with Drag and Drop

带拖放功能的TreeView

xml

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

csharp

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

xml

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

csharp

private void TreeView_ItemDropping(object sender, TreeViewItemDroppingEventArgs e)
{
    // 验证拖放操作
    if (!IsValidDrop(e.TargetNode, e.DraggingNodes))
    {
        e.Handled = true; // 取消拖放
    }
}

Key Properties

核心属性

Property	Type	Description
`ItemsSource`	IEnumerable	Data source for bound mode
`ChildPropertyName`	string	Property name for child collection
`SelectionMode`	SelectionMode	Single, Multiple, Extended, etc.
`SelectedItem`	object	Currently selected item
`SelectedItems`	ObservableCollection	Multiple selected items
`CheckBoxMode`	CheckBoxMode	None, Default, Recursive
`CheckedItems`	ObservableCollection	Checked items collection
`AllowDragging`	bool	Enable drag and drop
`AllowEditing`	bool	Enable inline editing
`AutoExpandMode`	AutoExpandMode	AllNodes, RootNodes, None
`ExpandActionTrigger`	ExpandActionTrigger	Node or Expander click
`ShowLines`	bool	Display tree lines
`ItemTemplate`	DataTemplate	Template for item display
`EditTemplate`	DataTemplate	Template for editing mode
`ExpanderTemplate`	DataTemplate	Template for expander icon

属性	类型	描述
`ItemsSource`	IEnumerable	绑定模式的数据源
`ChildPropertyName`	string	子集合的属性名称
`SelectionMode`	SelectionMode	单选、多选、扩展选择等
`SelectedItem`	object	当前选中的项
`SelectedItems`	ObservableCollection	多个选中项的集合
`CheckBoxMode`	CheckBoxMode	无、默认、递归
`CheckedItems`	ObservableCollection	已勾选项的集合
`AllowDragging`	bool	启用拖放
`AllowEditing`	bool	启用内联编辑
`AutoExpandMode`	AutoExpandMode	所有节点、根节点、无
`ExpandActionTrigger`	ExpandActionTrigger	节点或展开器点击
`ShowLines`	bool	显示树形连线
`ItemTemplate`	DataTemplate	项展示的模板
`EditTemplate`	DataTemplate	编辑模式的模板
`ExpanderTemplate`	DataTemplate	展开器图标的模板

Common Use Cases

常见使用场景

File Explorer

文件资源管理器

Display folder and file hierarchies with icons, allowing users to navigate, select, and manage files with drag-and-drop.

展示文件夹和文件的层级结构，带图标，允许用户导航、选择并通过拖放管理文件。

Organizational Chart

组织结构图

Show company hierarchy with employee nodes, supporting selection and expansion to view team structures.

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

Category Management

分类管理

Display product categories with checkboxes for multi-selection, enabling bulk operations on category trees.

展示产品分类，带复选框支持多选，允许对分类树执行批量操作。

Project Structure

项目结构

Show project files and folders with load-on-demand for large projects, supporting inline editing of file names.

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

Settings/Preferences Tree

设置/偏好树形菜单

Display nested configuration options with checkboxes for enabling/disabling features hierarchically.

展示嵌套的配置选项，带复选框以层级方式启用/禁用功能。

Menu/Navigation Tree

菜单/导航树形结构

Create hierarchical navigation menus with expandable sections and visual tree lines.

Next Steps: Navigate to the specific reference documentation above based on the feature you need to implement. Start with getting-started.md for initial setup, then explore other features as needed.

创建层级导航菜单，带可展开的章节和可视化树形连线。

下一步： 根据你需要实现的功能，导航到上面对应的参考文档。从getting-started.md开始进行初始设置，然后根据需要探索其他功能。