syncfusion-winforms-treeview（同步融合 winforms 树视图）

Implementing TreeViews in Windows Forms

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

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.

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

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

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

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

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

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

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

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

Sorting

📄 Read: references/sorting.md

• Runtime sorting capabilities
• Sort methods and properties
• Custom sorting logic
• Sorting with data binding
• Performance considerations

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

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

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

ScrollBar Customization

📄 Read: references/scrollbar-customization.md

• ScrollBar properties and configuration
• Automatic scrolling support
• Custom scrollbar appearance
• Scroll behavior configuration

Quick Start Example

Basic TreeView Setup

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

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

When: Building tree structure dynamically from code

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

When: Binding to single table with parent-child relationships

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

When: Working with large datasets, need lazy loading

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

When: Users need to reorder nodes via drag-drop

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

When: Working with 1000+ nodes, experiencing slow load times

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

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)

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

Node Properties (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

Key Events

Selection Events

• AfterSelect - After node selection changes
• BeforeSelect - Before node selection changes
• NodeSelected - Node selected event

Expand/Collapse Events

• BeforeExpand - Before node expands (use for load on demand)
• AfterExpand - After node expands
• BeforeCollapse - Before node collapses
• AfterCollapse - After node collapses

Drag-Drop Events

• ItemDrag - Node drag initiated
• DragDrop - Item dropped on control
• DragEnter - Drag enters control bounds
• DragOver - Drag over control bounds

Edit Events

• BeforeEdit - Before node edit starts
• AfterEdit - After node edit completes

Common Use Cases

Use Case 1: File Explorer

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

Use Case 2: Organization Chart

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

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

Use Case 4: Database Schema Visualizer

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

Use Case 5: XML/JSON Editor

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

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