syncfusion-winforms-treeview

在 Windows Forms 中实现 TreeView

何时使用此技能

在以下情况下，始终立即使用此技能：

• 用户需要以树形结构显示分层数据
• 构建文件资源管理器、文件夹浏览器或目录导航
• 实现组织结构图、类别树或嵌套菜单
• 需要具有可展开／折叠节点的父子关系
• 处理自引用数据或数据关系
• 需要通过拖放重新排列树节点
• 实现支持插入／删除／重命名操作的可编辑树结构
• 需要针对大型树数据集（1000+ 个节点）进行性能优化
• 用户提及：TreeView、分层数据、树形结构、可展开节点、父子关系

组件概述

Syncfusion TreeViewAdv 控件以树形结构显示分层数据，并提供超出标准 Windows Forms TreeView 的高级功能。它全面支持数据绑定、拖放、虚拟化、编辑和丰富的自定义选项。

主要功能

• 高级数据绑定： 自引用、数据关系、对象关系绑定
• 拖放： 完整的拖放支持，提供视觉反馈和验证
• 性能： 虚拟化可支持 20,000+ 个节点，延迟极低
• 节点自定义： 复选框、选项按钮、图像、自定义样式
• 编辑操作： 动态插入、删除、重命名，并与数据源同步
• 按需加载： 延迟加载子节点，提升性能
• 丰富外观： 主题、自定义样式、边框、颜色、字体
• 高级功能： 查找／替换、历史记录管理器（撤销／重做）、XML 持久化、打印
• 多选： 支持 CTRL+SHIFT 键进行多节点选择
• 上下文菜单： 关联菜单并设置显示／隐藏选项

常见用例

• 文件／文件夹浏览器界面
• 组织层级结构显示
• 类别／子类别导航
• 项目／任务树结构
• 设置／配置树
• XML／JSON 数据可视化
• 数据库表关系
• 多级菜单系统

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• 通过设计器（从工具箱拖放）添加控件
• 在 C# 和 VB.NET 中手动添加控件
• 创建 TreeViewAdv 实例
• 通过 NodeCollection 编辑器添加节点
• 以编程方式添加节点
• 基本节点自定义（线条、加号／减号）
• 设置活动节点

数据绑定

📄 阅读： references/data-binding.md

• 绑定到自引用数据（包含父子关系的单个表）
• ParentMember、ChildMember、SelfRelationRootValue 属性
• 绑定到数据关系（多个关联表）
• 绑定到对象关系数据（自定义对象）
• 配置 DataSource、DisplayMember、ValueMember
• 将树与数据源更改同步

节点自定义

📄 阅读： references/node-customization.md

• 根线和连接线（ShowLines、ShowRootLines）
• 父节点的加号／减号
• 使用 ShowPlusOnExpand 指示展开状态
• 使用 CheckBoxes 选择节点（ShowCheckBoxes）
• 用于单选样式选择的 OptionButtons
• 节点级与控件级属性
• 展开／折叠状态的图像
• 左侧、右侧和状态图像源

外观和样式

📄 阅读： references/appearance-styling.md

• 边框自定义（BorderStyle、BorderSingle、BorderColor）
• 2D 与 3D 边框（FixedSingle、Fixed3D）
• 边框样式（Solid、Dashed、Dotted、Inset、Outset）
• 节点外观（字体、颜色、背景）
• 全局样式与节点专属样式
• TreeNodeAdv 自定义属性
• 样式架构概述
• 主题支持和类似 Office 的样式

拖放

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

• 拖放功能概述
• 拖放事件处理（DragDrop、DragEnter、DragLeave、DragOver）
• 用于启动拖放操作的 ItemDrag 事件
• GiveFeedback 和 QueryContinueDrag 事件
• 自定义拖放反馈和验证
• 高级拖放场景
• 控件间拖放支持

编辑操作

📄 阅读： references/editing-operations.md

• 动态更新（插入、删除、重命名）
• 与数据源同步
• GridGroupingControl 集成
• 运行时节点操作
• 用于数据更新的 AcceptChanges 模式
• 双向反映更改

排序

📄 阅读： references/sorting.md

• 运行时排序功能
• 排序方法和属性
• 自定义排序逻辑
• 数据绑定时排序
• 性能注意事项

按需加载

📄 阅读： references/load-on-demand.md

• LoadOnDemand 功能概述
• 用于提升性能的延迟加载
• BeforeExpand 事件处理
• 动态添加子节点
• 用于获取节点路径的 GetPath 方法
• AddSeparatorAtEnd 属性

性能优化

📄 阅读： references/performance-optimization.md

• 使用 EnableVirtualization 处理大型数据集
• 虚拟化的优势（20,000+ 个节点）
• SuspendExpandRecalculate 优化
• RecalculateExpansion 属性
• 大型树的最佳实践
• 性能基准测试

高级功能

📄 阅读： references/advanced-features.md

• 查找和替换功能
• 搜索功能
• History Manager（撤销/重做操作）
• 保存和加载 XML（持久化）
• 打印支持和自定义
• 带显示/隐藏选项的上下文菜单
• 使用 CTRL+SHIFT 键进行多选

滚动条自定义

📄 阅读： references/scrollbar-customization.md

• 滚动条属性和配置
• 自动滚动支持
• 自定义滚动条外观
• 滚动行为配置

快速入门示例

基本 TreeView 设置

using Syncfusion.Windows.Forms.Tools;

namespace WinFormsTreeApp
{
    public partial class Form1 : Form
    {
        private TreeViewAdv treeViewAdv1;
        
        public Form1()
        {
            InitializeComponent();
            InitializeTreeView();
        }
        
        private void InitializeTreeView()
        {
            // Create TreeViewAdv instance
            treeViewAdv1 = new TreeViewAdv();
            treeViewAdv1.Location = new System.Drawing.Point(20, 20);
            treeViewAdv1.Size = new System.Drawing.Size(300, 400);
            
            // Create nodes
            TreeNodeAdv parentNode1 = new TreeNodeAdv("Parent 1");
            TreeNodeAdv childNode1 = new TreeNodeAdv("Child 1");
            TreeNodeAdv childNode2 = new TreeNodeAdv("Child 2");
            
            // Build hierarchy
            parentNode1.Nodes.AddRange(new TreeNodeAdv[] { childNode1, childNode2 });
            
            TreeNodeAdv parentNode2 = new TreeNodeAdv("Parent 2");
            TreeNodeAdv childNode3 = new TreeNodeAdv("Child 3");
            parentNode2.Nodes.Add(childNode3);
            
            // Add root nodes
            treeViewAdv1.Nodes.AddRange(new TreeNodeAdv[] { parentNode1, parentNode2 });
            
            // Customize appearance
            treeViewAdv1.ShowLines = true;
            treeViewAdv1.ShowRootLines = true;
            treeViewAdv1.ShowPlusMinus = true;
            
            // Add to form
            this.Controls.Add(treeViewAdv1);
        }
    }
}

数据绑定示例

// Self-referencing data binding
DataTable dataTable = CreateHierarchicalData();

treeViewAdv1.DataSource = dataTable;
treeViewAdv1.DisplayMember = "Name";
treeViewAdv1.ValueMember = "ID";
treeViewAdv1.ParentMember = "ParentID";
treeViewAdv1.ChildMember = "ID";
treeViewAdv1.SelfRelationRootValue = DBNull.Value;

常见模式

模式 1：以编程方式创建节点

适用场景： 通过代码动态构建树结构

// Create nodes with constructor
TreeNodeAdv node = new TreeNodeAdv("Node Text");

// Set properties
node.Text = "Updated Text";
node.ShowCheckBox = true;
node.Tag = customDataObject;

// Add children
node.Nodes.Add(new TreeNodeAdv("Child"));

// Add to tree
treeViewAdv1.Nodes.Add(node);

模式 2：自引用数据绑定

适用场景： 绑定到具有父子关系的单个表

// Setup data source
treeViewAdv1.DataSource = employeeTable;
treeViewAdv1.DisplayMember = "EmployeeName";
treeViewAdv1.ValueMember = "EmployeeID";
treeViewAdv1.ParentMember = "ManagerID";
treeViewAdv1.ChildMember = "EmployeeID";
treeViewAdv1.SelfRelationRootValue = DBNull.Value; // Root nodes have null parent

模式 3：按需加载

适用场景： 处理大型数据集，需要延迟加载

// Enable load on demand
treeViewAdv1.LoadOnDemand = true;

// Handle BeforeExpand to load children
treeViewAdv1.BeforeExpand += (sender, e) => 
{
    TreeNodeAdv node = e.Node;
    
    // Check if children already loaded
    if (node.Nodes.Count == 0)
    {
        // Load children from data source
        var children = LoadChildNodesFromDatabase(node.Tag);
        
        foreach (var child in children)
        {
            TreeNodeAdv childNode = new TreeNodeAdv(child.Name);
            childNode.Tag = child;
            node.Nodes.Add(childNode);
        }
    }
};

模式 4：拖放重新排序节点

适用场景： 用户需要通过拖放重新排列节点

// Enable drag-drop
treeViewAdv1.AllowDrop = true;

// Handle ItemDrag
treeViewAdv1.ItemDrag += (sender, e) => 
{
    if (e.Item is TreeNodeAdv node)
    {
        treeViewAdv1.DoDragDrop(node, DragDropEffects.Move);
    }
};

// Handle DragDrop
treeViewAdv1.DragDrop += (sender, e) => 
{
    TreeNodeAdv sourceNode = (TreeNodeAdv)e.Data.GetData(typeof(TreeNodeAdv));
    TreeNodeAdv targetNode = treeViewAdv1.GetNodeAtPoint(treeViewAdv1.PointToClient(new Point(e.X, e.Y)));
    
    if (targetNode != null && sourceNode != targetNode)
    {
        sourceNode.Remove();
        targetNode.Nodes.Add(sourceNode);
        targetNode.Expand();
    }
};

模式 5：大型树的性能优化

适用场景： 处理 1000+ 个节点，遇到加载缓慢的问题

// Enable virtualization
treeViewAdv1.EnableVirtualization = true;

// Optimize expand/collapse
treeViewAdv1.SuspendExpandRecalculate = true;
treeViewAdv1.RecalculateExpansion = false;

// Suspend layout during bulk operations
treeViewAdv1.BeginUpdate();
try
{
    // Add thousands of nodes
    for (int i = 0; i < 10000; i++)
    {
        treeViewAdv1.Nodes.Add(new TreeNodeAdv($"Node {i}"));
    }
}
finally
{
    treeViewAdv1.EndUpdate();
}

关键属性

数据绑定属性

• DataSource - 数据源对象（DataTable、List 等）
• DisplayMember - 用于显示节点文本的字段
• ValueMember - 节点值字段
• ParentMember - 自引用的父级 ID 字段
• ChildMember - 自引用的子级 ID 字段
• SelfRelationRootValue - 表示根节点的值

外观属性

• ShowLines - 显示节点之间的连接线
• ShowRootLines - 显示根节点之间的连线
• ShowPlusMinus - 显示展开/折叠按钮
• ShowCheckBoxes - 在节点上显示复选框
• ShowOptionButtons - 显示选项按钮（单选样式）
• BorderStyle - 边框样式（None、FixedSingle、Fixed3D）

行为属性

• LoadOnDemand - 启用子节点延迟加载
• AllowDrop - 启用拖放操作
• EnableVirtualization - 启用虚拟化以提升性能
• SuspendExpandRecalculate - 优化展开/折叠性能
• RecalculateExpansion - 控制加载时的尺寸计算

节点属性（TreeNodeAdv）

• Text - 节点显示文本
• Tag - 自定义数据对象
• Checked - 复选框状态
• Expanded - 展开/折叠状态
• ShowCheckBox - 显示此节点的复选框
• ShowPlusMinus - 显示此节点的加号/减号

主要事件

选择事件

• AfterSelect - 节点选择更改后触发
• BeforeSelect - 节点选择更改前触发
• NodeSelected - 节点已选中事件

展开/折叠事件

• BeforeExpand - 节点展开前触发（用于按需加载）
• AfterExpand - 节点展开后触发
• BeforeCollapse - 节点折叠前触发
• AfterCollapse - 节点折叠后触发

拖放事件

• ItemDrag - 开始拖动节点
• DragDrop - 项目放置到控件上
• DragEnter - 拖动进入控件范围
• DragOver - 拖动经过控件范围

编辑事件

• BeforeEdit - 开始编辑节点前触发
• AfterEdit - 完成节点编辑后触发

常见用例

用例 1：文件资源管理器

构建类似 Windows 资源管理器的界面，显示文件夹和文件：

• 使用按需加载浏览目录
• 通过 LeftImageList 添加文件夹/文件图标
• 处理双击以打开文件
• 为文件操作实现上下文菜单

用例 2：组织结构图

显示包含员工的公司层级结构：

• 绑定到包含自引用数据的员工表
• 将员工照片显示为节点图像
• 添加复选框以支持多选操作
• 实现拖放以调整组织结构

用例 3：设置树

创建分层的设置/偏好设置界面：

• 按类别在树结构中对设置分组
• 使用选项按钮设置单选项
• 使用复选框设置布尔选项
• 通过 XML 持久化保存/加载设置

用例 4：数据库架构可视化工具

显示数据库表及其关系：

• 将数据库架构加载到树中
• 将表显示为父节点，将列显示为子节点
• 添加图标以指示数据类型
• 启用查找/替换以搜索架构

用例 5：XML/JSON 编辑器

用于分层数据格式的可视化编辑器：

• 将 XML/JSON 解析为树结构
• 启用节点值的内联编辑
• 通过 History Manager 实现撤销/重做
• 将更改保存回 XML/JSON 格式

故障排除

问题： 数据绑定后节点未显示

• 解决方案： 确认 DataSource 不为 null，检查 ParentMember/ChildMember 是否与列名匹配，并确保 SelfRelationRootValue 与根节点模式匹配

问题： 大型数据集的性能缓慢

• 解决方案： 启用 EnableVirtualization，使用 LoadOnDemand 进行延迟加载，并设置 SuspendExpandRecalculate = true

问题： 拖放不起作用

• 解决方案： 设置 AllowDrop = true，实现 ItemDrag 和 DragDrop 事件处理程序，并检查 DragDropEffects

问题： 更改未反映到绑定的数据源中

• 解决方案： 修改后对 DataTable 调用 AcceptChanges()，确认 DataSource 绑定处于活动状态

问题： 父节点未显示加号/减号

• 解决方案： 确认 ShowPlusMinus = true，检查节点是否有子节点；对于 LoadOnDemand，确保已配置 ShowPlusOnExpand