syncfusion-winforms-treeview

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing TreeViews in Windows Forms

在Windows Forms中实现TreeView

When to Use This Skill

何时使用本技能

Use this skill ALWAYS and immediately when:
  • User needs to display hierarchical data in a tree structure
  • Building file explorers, folder browsers, or directory navigation
  • Implementing organization charts, category trees, or nested menus
  • Need parent-child relationships with expandable/collapsible nodes
  • Working with self-referencing data or data relations
  • Need drag-and-drop reordering of tree nodes
  • Implementing editable tree structures with insert/delete/rename operations
  • Performance optimization needed for large tree datasets (1000+ nodes)
  • User mentions: TreeView, hierarchical data, tree structure, expandable nodes, parent-child
满足以下任一条件时请立即使用本技能:
  • 用户需要在树结构中展示层级数据
  • 开发文件资源管理器、文件夹浏览器或目录导航功能
  • 实现组织架构图、分类树或嵌套菜单
  • 需要具备可展开/折叠节点的父子关系结构
  • 处理自引用数据或数据关系
  • 需要支持拖拽重排树节点
  • 实现支持插入/删除/重命名操作的可编辑树结构
  • 针对包含1000+节点的大型树数据集做性能优化
  • 用户提到以下关键词:TreeView、层级数据、树结构、可展开节点、父子关系

Component Overview

组件概述

The Syncfusion TreeViewAdv control displays hierarchical data in a tree structure with advanced features beyond the standard Windows Forms TreeView. It provides comprehensive support for data binding, drag-and-drop, virtualization, editing, and extensive customization options.
Syncfusion TreeViewAdv 控件用于以树结构展示层级数据,具备标准Windows Forms TreeView之外的高级功能。它完整支持数据绑定、拖拽、虚拟化、编辑能力,还提供了丰富的自定义选项。

Key Features

核心特性

  • Advanced Data Binding: Self-referencing, data relations, object-relational binding
  • Drag-and-Drop: Full drag-drop support with visual feedback and validation
  • Performance: Virtualization for 20,000+ nodes with minimal delay
  • Node Customization: Checkboxes, option buttons, images, custom styles
  • Editing Operations: Dynamic insert, delete, rename with data source sync
  • Load on Demand: Lazy loading of child nodes for better performance
  • Rich Appearance: Themes, custom styles, borders, colors, fonts
  • Advanced Features: Find/replace, history manager (undo/redo), XML persistence, printing
  • Multi-Selection: CTRL+SHIFT key support for multiple node selection
  • Context Menus: Associate menus with show/hide options
  • 高级数据绑定: 支持自引用、数据关系、对象关系绑定
  • 拖拽能力: 完整的拖拽支持,附带视觉反馈和校验
  • 高性能: 虚拟化能力支持20000+节点,延迟极低
  • 节点自定义: 支持复选框、单选按钮、图片、自定义样式
  • 编辑操作: 动态增删改,可与数据源自动同步
  • 按需加载: 子节点懒加载优化性能
  • 丰富的外观配置: 主题、自定义样式、边框、颜色、字体
  • 高级功能: 查找/替换、历史管理器(撤销/重做)、XML持久化、打印
  • 多选能力: 支持CTRL+SHIFT快捷键多选节点
  • 上下文菜单: 可关联菜单并配置显隐选项

Common Use Cases

常见使用场景

  • File/folder browser interfaces
  • Organization hierarchy displays
  • Category/subcategory navigation
  • Project/task tree structures
  • Settings/configuration trees
  • XML/JSON data visualization
  • Database table relationships
  • Multi-level menu systems
  • 文件/文件夹浏览器界面
  • 组织层级展示
  • 分类/子分类导航
  • 项目/任务树结构
  • 设置/配置树
  • XML/JSON数据可视化
  • 数据库表关系展示
  • 多级菜单系统

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
  • Installation and NuGet package setup
  • Adding control via Designer (Toolbox drag-drop)
  • Adding control manually in C# and VB.NET
  • Creating TreeViewAdv instances
  • Adding nodes through NodeCollection Editor
  • Adding nodes programmatically
  • Basic node customization (lines, plus/minus signs)
  • Assigning active nodes
📄 阅读: references/getting-started.md
  • 安装与NuGet包配置
  • 通过设计器添加控件(工具箱拖拽)
  • 在C#和VB.NET中手动添加控件
  • 创建TreeViewAdv实例
  • 通过NodeCollection编辑器添加节点
  • 编程式添加节点
  • 基础节点自定义(连线、加减号按钮)
  • 分配激活节点

Data Binding

数据绑定

📄 Read: references/data-binding.md
  • Binding to self-referencing data (single table with parent-child)
  • ParentMember, ChildMember, SelfRelationRootValue properties
  • Binding to data relations (multiple related tables)
  • Binding to object-relational data (custom objects)
  • DataSource, DisplayMember, ValueMember configuration
  • Synchronizing tree with data source changes
📄 阅读: references/data-binding.md
  • 绑定自引用数据(包含父子关系的单表)
  • ParentMember、ChildMember、SelfRelationRootValue属性配置
  • 绑定数据关系(多个关联表)
  • 绑定对象关系数据(自定义对象)
  • DataSource、DisplayMember、ValueMember配置
  • 树结构与数据源变更同步

Node Customization

节点自定义

📄 Read: references/node-customization.md
  • Root lines and connecting lines (ShowLines, ShowRootLines)
  • Plus/Minus signs for parent nodes
  • ShowPlusOnExpand for expanded state indicators
  • CheckBoxes for node selection (ShowCheckBoxes)
  • OptionButtons for radio-style selection
  • Node-level vs control-level properties
  • Images for expanded/collapsed states
  • Left, right, and state image sources
📄 阅读: references/node-customization.md
  • 根节点连线与连接线条(ShowLines、ShowRootLines)
  • 父节点的加减号按钮
  • ShowPlusOnExpand配置展开状态指示器
  • 节点选择用复选框(ShowCheckBoxes)
  • 单选样式选择用OptionButtons
  • 节点级别与控件级别的属性区别
  • 展开/折叠状态的图片配置
  • 左侧、右侧和状态图片源配置

Appearance and Styling

外观与样式

📄 Read: references/appearance-styling.md
  • Border customization (BorderStyle, BorderSingle, BorderColor)
  • 2D vs 3D borders (FixedSingle, Fixed3D)
  • Border styles (Solid, Dashed, Dotted, Inset, Outset)
  • Node appearance (font, colors, backgrounds)
  • Global styles vs node-specific styles
  • TreeNodeAdv customization properties
  • Styles architecture overview
  • Theme support and Office-like styling
📄 阅读: references/appearance-styling.md
  • 边框自定义(BorderStyle、BorderSingle、BorderColor)
  • 2D与3D边框(FixedSingle、Fixed3D)
  • 边框样式(实线、虚线、点状、内凹、外凸)
  • 节点外观(字体、颜色、背景)
  • 全局样式与节点专属样式
  • TreeNodeAdv自定义属性
  • 样式架构概览
  • 主题支持与Office风格样式

Drag and Drop

拖拽操作

📄 Read: references/drag-and-drop.md
  • Drag-drop functionality overview
  • Drag-drop event handling (DragDrop, DragEnter, DragLeave, DragOver)
  • ItemDrag event for initiating drag operations
  • GiveFeedback and QueryContinueDrag events
  • Custom drag feedback and validation
  • Advanced drag-drop scenarios
  • Inter-control drag-drop support
📄 阅读: references/drag-and-drop.md
  • 拖拽功能概览
  • 拖拽事件处理(DragDrop、DragEnter、DragLeave、DragOver)
  • 触发拖拽操作的ItemDrag事件
  • GiveFeedback与QueryContinueDrag事件
  • 自定义拖拽反馈与校验
  • 高级拖拽场景
  • 跨控件拖拽支持

Editing Operations

编辑操作

📄 Read: references/editing-operations.md
  • Dynamic updates (insert, delete, rename)
  • Synchronizing with data source
  • GridGroupingControl integration
  • Runtime node manipulation
  • AcceptChanges pattern for data updates
  • Reflecting changes bidirectionally
📄 阅读: references/editing-operations.md
  • 动态更新(插入、删除、重命名)
  • 与数据源同步
  • GridGroupingControl集成
  • 运行时节点操作
  • 数据更新的AcceptChanges模式
  • 双向变更同步

Sorting

排序

📄 Read: references/sorting.md
  • Runtime sorting capabilities
  • Sort methods and properties
  • Custom sorting logic
  • Sorting with data binding
  • Performance considerations
📄 阅读: references/sorting.md
  • 运行时排序能力
  • 排序方法与属性
  • 自定义排序逻辑
  • 数据绑定场景下的排序
  • 性能注意事项

Load on Demand

按需加载

📄 Read: references/load-on-demand.md
  • LoadOnDemand feature overview
  • Lazy loading for performance
  • BeforeExpand event handling
  • Adding sub-nodes dynamically
  • GetPath method for node paths
  • AddSeparatorAtEnd property
📄 阅读: references/load-on-demand.md
  • LoadOnDemand功能概览
  • 懒加载优化性能
  • BeforeExpand事件处理
  • 动态添加子节点
  • 获取节点路径的GetPath方法
  • AddSeparatorAtEnd属性

Performance Optimization

性能优化

📄 Read: references/performance-optimization.md
  • EnableVirtualization for large datasets
  • Virtualization benefits (20,000+ nodes)
  • SuspendExpandRecalculate optimization
  • RecalculateExpansion property
  • Best practices for large trees
  • Performance benchmarks
📄 阅读: references/performance-optimization.md
  • 为大型数据集开启EnableVirtualization
  • 虚拟化收益(支持20000+节点)
  • SuspendExpandRecalculate优化
  • RecalculateExpansion属性
  • 大型树结构开发最佳实践
  • 性能基准

Advanced Features

高级功能

📄 Read: references/advanced-features.md
  • Find and Replace functionality
  • Search capabilities
  • History Manager (undo/redo operations)
  • Save and Load XML (persistence)
  • Printing support and customization
  • Context menus with show/hide options
  • Multi-selection with CTRL+SHIFT keys
📄 阅读: references/advanced-features.md
  • 查找与替换功能
  • 搜索能力
  • 历史管理器(撤销/重做操作)
  • XML保存与加载(持久化)
  • 打印支持与自定义
  • 支持显隐配置的上下文菜单
  • 支持CTRL+SHIFT快捷键多选

ScrollBar Customization

滚动条自定义

📄 Read: references/scrollbar-customization.md
  • ScrollBar properties and configuration
  • Automatic scrolling support
  • Custom scrollbar appearance
  • Scroll behavior configuration
📄 阅读: references/scrollbar-customization.md
  • 滚动条属性与配置
  • 自动滚动支持
  • 自定义滚动条外观
  • 滚动行为配置

Quick Start Example

快速入门示例

Basic TreeView Setup

基础TreeView配置

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

Data Binding Example

数据绑定示例

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

Common Patterns

常用模式

Pattern 1: Programmatic Node Creation

模式1:编程式创建节点

When: Building tree structure dynamically from code
csharp
// 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);
适用场景: 从代码动态构建树结构
csharp
// 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);

Pattern 2: Self-Referencing Data Binding

模式2:自引用数据绑定

When: Binding to single table with parent-child relationships
csharp
// 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
适用场景: 绑定包含父子关系的单表数据
csharp
// 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

Pattern 3: Load on Demand

模式3:按需加载

When: Working with large datasets, need lazy loading
csharp
// 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);
        }
    }
};
适用场景: 处理大型数据集,需要懒加载能力
csharp
// 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);
        }
    }
};

Pattern 4: Drag-Drop Node Reordering

模式4:拖拽节点重排

When: Users need to reorder nodes via drag-drop
csharp
// 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();
    }
};
适用场景: 用户需要通过拖拽重排节点顺序
csharp
// 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();
    }
};

Pattern 5: Performance Optimization for Large Trees

模式5:大型树结构性能优化

When: Working with 1000+ nodes, experiencing slow load times
csharp
// 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();
}
适用场景: 处理1000+节点,加载速度缓慢
csharp
// 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();
}

Key Properties

核心属性

Data Binding Properties

数据绑定属性

  • DataSource
    - Data source object (DataTable, List, etc.)
  • DisplayMember
    - Field for node text display
  • ValueMember
    - Field for node value
  • ParentMember
    - Parent ID field for self-referencing
  • ChildMember
    - Child ID field for self-referencing
  • SelfRelationRootValue
    - Value indicating root nodes
  • DataSource
    - 数据源对象(DataTable、List等)
  • DisplayMember
    - 节点文本展示对应的字段
  • ValueMember
    - 节点值对应的字段
  • ParentMember
    - 自引用场景下的父ID字段
  • ChildMember
    - 自引用场景下的子ID字段
  • SelfRelationRootValue
    - 标识根节点的取值

Appearance Properties

外观属性

  • ShowLines
    - Display connecting lines between nodes
  • ShowRootLines
    - Display lines between root nodes
  • ShowPlusMinus
    - Display expand/collapse buttons
  • ShowCheckBoxes
    - Display checkboxes on nodes
  • ShowOptionButtons
    - Display option buttons (radio style)
  • BorderStyle
    - Border style (None, FixedSingle, Fixed3D)
  • ShowLines
    - 展示节点间的连接线
  • ShowRootLines
    - 展示根节点之间的连线
  • ShowPlusMinus
    - 展示展开/折叠按钮
  • ShowCheckBoxes
    - 展示节点复选框
  • ShowOptionButtons
    - 展示单选按钮(单选样式)
  • BorderStyle
    - 边框样式(None、FixedSingle、Fixed3D)

Behavior Properties

行为属性

  • LoadOnDemand
    - Enable lazy loading of child nodes
  • AllowDrop
    - Enable drag-drop operations
  • EnableVirtualization
    - Enable virtualization for performance
  • SuspendExpandRecalculate
    - Optimize expand/collapse performance
  • RecalculateExpansion
    - Control dimension calculation on load
  • LoadOnDemand
    - 开启子节点懒加载
  • AllowDrop
    - 开启拖拽操作
  • EnableVirtualization
    - 开虚拟化提升性能
  • SuspendExpandRecalculate
    - 优化展开/折叠性能
  • RecalculateExpansion
    - 控制加载时的尺寸计算逻辑

Node Properties (TreeNodeAdv)

节点属性(TreeNodeAdv)

  • Text
    - Node display text
  • Tag
    - Custom data object
  • Checked
    - Checkbox state
  • Expanded
    - Expand/collapse state
  • ShowCheckBox
    - Show checkbox for this node
  • ShowPlusMinus
    - Show plus/minus for this node
  • Text
    - 节点展示文本
  • Tag
    - 自定义数据对象
  • Checked
    - 复选框状态
  • Expanded
    - 展开/折叠状态
  • ShowCheckBox
    - 为当前节点展示复选框
  • ShowPlusMinus
    - 为当前节点展示加减号按钮

Key Events

核心事件

Selection Events

选择事件

  • AfterSelect
    - After node selection changes
  • BeforeSelect
    - Before node selection changes
  • NodeSelected
    - Node selected event
  • AfterSelect
    - 节点选择变更后触发
  • BeforeSelect
    - 节点选择变更前触发
  • NodeSelected
    - 节点被选中时触发

Expand/Collapse Events

展开/折叠事件

  • BeforeExpand
    - Before node expands (use for load on demand)
  • AfterExpand
    - After node expands
  • BeforeCollapse
    - Before node collapses
  • AfterCollapse
    - After node collapses
  • BeforeExpand
    - 节点展开前触发(用于按需加载)
  • AfterExpand
    - 节点展开后触发
  • BeforeCollapse
    - 节点折叠前触发
  • AfterCollapse
    - 节点折叠后触发

Drag-Drop Events

拖拽事件

  • ItemDrag
    - Node drag initiated
  • DragDrop
    - Item dropped on control
  • DragEnter
    - Drag enters control bounds
  • DragOver
    - Drag over control bounds
  • ItemDrag
    - 节点拖拽开始时触发
  • DragDrop
    - 元素被拖放到控件上时触发
  • DragEnter
    - 拖拽进入控件边界时触发
  • DragOver
    - 拖拽在控件边界内移动时触发

Edit Events

编辑事件

  • BeforeEdit
    - Before node edit starts
  • AfterEdit
    - After node edit completes
  • BeforeEdit
    - 节点编辑开始前触发
  • AfterEdit
    - 节点编辑完成后触发

Common Use Cases

常见使用场景

Use Case 1: File Explorer

场景1:文件资源管理器

Build Windows Explorer-like interface with folders and files:
  • Use load on demand for directory browsing
  • Add folder/file icons via LeftImageList
  • Handle double-click to open files
  • Implement context menus for file operations
构建类似Windows资源管理器的文件和文件夹展示界面:
  • 使用按需加载实现目录浏览
  • 通过LeftImageList添加文件夹/文件图标
  • 处理双击事件打开文件
  • 实现文件操作对应的上下文菜单

Use Case 2: Organization Chart

场景2:组织架构图

Display company hierarchy with employees:
  • Bind to employee table with self-referencing data
  • Show employee photos as node images
  • Add checkboxes for multi-select operations
  • Implement drag-drop for reorganization
展示公司员工层级关系:
  • 绑定包含自引用关系的员工表
  • 展示员工照片作为节点图片
  • 添加复选框支持多选操作
  • 实现拖拽能力支持组织架构调整

Use Case 3: Settings Tree

场景3:设置树

Create hierarchical settings/preferences interface:
  • Group settings by category in tree structure
  • Use option buttons for single-choice settings
  • Use checkboxes for boolean settings
  • Save/load settings via XML persistence
创建设置/偏好的层级展示界面:
  • 按分类将设置分组到树结构中
  • 使用单选按钮实现单选类设置
  • 使用复选框实现布尔类型设置
  • 通过XML持久化实现设置的保存/加载

Use Case 4: Database Schema Visualizer

场景4:数据库 schema 可视化工具

Display database tables and relationships:
  • Load database schema into tree
  • Show tables as parent nodes, columns as children
  • Add icons to indicate data types
  • Enable find/replace for schema search
展示数据库表和关系:
  • 将数据库schema加载到树结构中
  • 表作为父节点,列作为子节点展示
  • 添加图标标识数据类型
  • 开启查找/替换实现schema搜索

Use Case 5: XML/JSON Editor

场景5:XML/JSON编辑器

Visual editor for hierarchical data formats:
  • Parse XML/JSON into tree structure
  • Enable inline editing of node values
  • Implement undo/redo via History Manager
  • Save changes back to XML/JSON format
层级数据格式的可视化编辑器:
  • 将XML/JSON解析为树结构
  • 支持节点值的行内编辑
  • 通过历史管理器实现撤销/重做
  • 将修改保存回XML/JSON格式

Troubleshooting

故障排查

Issue: Nodes not appearing after data binding
  • Solution: Verify DataSource is not null, check ParentMember/ChildMember match column names, ensure SelfRelationRootValue matches root node pattern
Issue: Performance slow with large datasets
  • Solution: Enable EnableVirtualization, use LoadOnDemand for lazy loading, set SuspendExpandRecalculate = true
Issue: Drag-drop not working
  • Solution: Set AllowDrop = true, implement ItemDrag and DragDrop event handlers, check DragDropEffects
Issue: Changes not reflecting in bound data source
  • Solution: Call AcceptChanges() on DataTable after modifications, verify DataSource binding is active
Issue: Plus/minus signs not showing for parent nodes
  • Solution: Verify ShowPlusMinus = true, check nodes have children, for LoadOnDemand ensure ShowPlusOnExpand is configured
问题: 数据绑定后节点没有展示
  • 解决方案: 确认DataSource不为空,检查ParentMember/ChildMember是否匹配列名,确保SelfRelationRootValue与根节点的取值匹配
问题: 大型数据集下性能缓慢
  • 解决方案: 开启EnableVirtualization,使用LoadOnDemand实现懒加载,设置SuspendExpandRecalculate = true
问题: 拖拽功能不生效
  • 解决方案: 设置AllowDrop = true,实现ItemDrag和DragDrop事件处理逻辑,检查DragDropEffects配置
问题: 变更没有同步到绑定的数据源
  • 解决方案: 修改后调用DataTable的AcceptChanges()方法,确认DataSource绑定处于激活状态
问题: 父节点的加减号按钮没有展示
  • 解决方案: 确认ShowPlusMinus = true,检查节点是否包含子节点,按需加载场景下确保ShowPlusOnExpand已正确配置