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

Implementing Syncfusion Blazor TreeView Component

The Blazor TreeView component displays hierarchical data in an expandable/collapsible tree structure. It supports local and remote data binding, single and multi-selection, editing, checkboxes, drag-drop reordering, virtualization for large datasets, filtering, and comprehensive event handling.

📋 Table of Contents

1. When to Use
2. Installation & Setup
3. Quick Start
4. Key Properties
5. Key Methods
6. Key Events
7. Common Patterns
8. Complete Reference Navigation

When to Use This Skill

Use the TreeView component when you need to:

• Display hierarchical data in a tree structure with expandable/collapsible nodes
• Single selection: Allow users to select one node from the tree
• Multi-selection: Enable selection of multiple tree nodes using Ctrl+Click and Shift+Click
• Checkbox selection: Provide checkbox-based multi-selection with automatic parent-child state management
• Edit nodes: Allow inline renaming or editing of node text
• Drag and drop: Enable reordering nodes within the hierarchy
• Filter and search: Implement search functionality to find nodes
• Remote data sources: Bind to Web APIs, OData services, or custom endpoints
• Handle events: Respond to expand, collapse, select, edit, and drag-drop actions
• Virtualization: Display large datasets (1000+ nodes) with smooth scrolling
• Custom styling: Apply icons, colors, and templates for nodes

Installation & Setup

Install Syncfusion NuGet packages and configure your Blazor project:

// 1. Install NuGet packages
// Install-Package Syncfusion.Blazor.Navigations -Version 26.1.35
// Install-Package Syncfusion.Blazor.Themes -Version 26.1.35

// 2. Add to _Imports.razor
@using Syncfusion.Blazor
@using Syncfusion.Blazor.Navigations

// 3. Register service in Program.cs
builder.Services.AddSyncfusionBlazor();

// 4. Add CSS theme to Index.html or _Layout.cshtml
<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />

Quick Start

@using Syncfusion.Blazor.Navigations

<SfTreeView TValue="MailItem">
    <TreeViewFieldsSettings TValue="MailItem"
        Id="Id"
        Text="FolderName"
        Child="Children"
        DataSource="@MyFolder">
    </TreeViewFieldsSettings>
    <TreeViewEvents TValue="MailItem" NodeSelected="OnNodeSelected"></TreeViewEvents>
</SfTreeView>

@code {
    public class MailItem
    {
        public string? Id { get; set; }
        public string? FolderName { get; set; }
        public List<MailItem>? Children { get; set; }
    }

    void OnNodeSelected(NodeSelectEventArgs args)
    {
        Console.WriteLine($"Selected: {args.NodeData.Text}");
    }

    List<MailItem> MyFolder = new()
    {
        new MailItem { Id = "1", FolderName = "Inbox", Children = new() },
        new MailItem { Id = "2", FolderName = "Sent", Children = new() }
    };
}

Key Properties

Key Methods

Key Events

Common Patterns

Pattern 1: Basic Selection

<SfTreeView TValue="Item" @bind-SelectedNodes="@SelectedIds">
    <TreeViewFieldsSettings TValue="Item" DataSource="@Items" />
    <TreeViewEvents TValue="Item" NodeSelected="OnSelect"></TreeViewEvents>
</SfTreeView>

@code {
    string[] SelectedIds = Array.Empty<string>();
    void OnSelect(NodeSelectEventArgs args) => Console.WriteLine(args.NodeData.Text);
}

Pattern 2: Multiple Selection

<SfTreeView TValue="Item" AllowMultiSelection="true" @bind-SelectedNodes="@SelectedIds">
    <TreeViewFieldsSettings TValue="Item" DataSource="@Items" />
</SfTreeView>

Pattern 3: Load on Demand

void OnNodeExpanded(NodeExpandEventArgs args)
{
    if (args.NodeData.HasChild && args.NodeData.Child == null)
    {
        // Load children from API
        args.NodeData.Child = await FetchChildren(args.NodeData.Id);
    }
}

Pattern 4: Drag and Drop

<SfTreeView TValue="Item" AllowDragAndDrop="true">
    <TreeViewFieldsSettings TValue="Item" DataSource="@Items" />
    <TreeViewEvents TValue="Item" NodeDropped="OnDropped"></TreeViewEvents>
</SfTreeView>

void OnDropped(DragAndDropEventArgs args) => UpdateHierarchy(args);

Pattern 5: Node Editing

<SfTreeView TValue="Item" AllowEditing="true" DoubleClickAction="DoubleClickAction.Edit">
    <TreeViewFieldsSettings TValue="Item" DataSource="@Items" />
    <TreeViewEvents TValue="Item" NodeEdited="OnEdited"></TreeViewEvents>
</SfTreeView>

void OnEdited(NodeEditEventArgs args) => SaveChanges(args.NodeData);

Pattern 6: Checkboxes

<SfTreeView TValue="Item" AllowCheckBoxes="true" ChildChecking="ChildCheckState.Both">
    <TreeViewFieldsSettings TValue="Item" DataSource="@Items" />
</SfTreeView>

var checked = treeRef.GetAllCheckedNodes();

Documentation and Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• Installation and NuGet package setup
• Project configuration by type (WebAssembly, Server, Web App, MAUI)
• CSS theme configuration
• Service registration and first TreeView component

Data Binding and Sources

📄 Read: references/data-binding.md

• Local data binding (hierarchical and self-referential structures)
• Remote data with OData, OData V4, and Web API adaptors
• Load on Demand for large datasets
• TreeViewFieldsSettings property mappings
• DataBound event for post-binding operations

Node Selection

📄 Read: references/node-selection.md

• Single node selection (default behavior)
• Multi-selection with AllowMultiSelection property
• Accessing selected node data via NodeSelected event
• Programmatic selection using SelectedNodes binding
• Selection validation and conditional selection

Expand and Collapse Actions

📄 Read: references/expand-collapse-actions.md

• Expand/collapse methods (ExpandAllAsync, CollapseAllAsync)
• ExpandedNodes two-way binding for programmatic control
• Initial expand state via data source
• Expand/collapse animations with TreeViewNodeAnimationSettings
• Load-on-demand child node loading via NodeExpanded event

Node Editing

📄 Read: references/node-editing.md

• Enable editing with AllowEditing property
• Double-click to enter edit mode
• BeginEditAsync method for programmatic edit entry
• NodeEditing and NodeEdited events for validation
• Rename operations with conflict detection

Checkbox Features

📄 Read: references/checkbox-features.md

• ShowCheckBox property for multi-item selection
• AutoCheck for automatic parent-child synchronization
• CheckedNodes two-way binding for programmatic control
• Getting checked nodes with filtering and iteration
• Permissions and role-based checkbox patterns

Events and Callbacks

📄 Read: references/events-handling.md

• Lifecycle events (Created, DataBound)
• Selection events (NodeSelected, SelectedNodesChanged)
• Expand/collapse events (NodeExpanded, NodeCollapsed)
• Edit events (NodeEditing, NodeEdited)
• Checkbox events (NodeChecking, NodeChecked)
• Drag-drop events (OnNodeDragStart, NodeDropped)
• Keyboard shortcuts (Enter, Delete, F2, Arrow keys)

Advanced Features

📄 Read: references/advanced-features.md

• Drag-and-drop with hierarchy reordering
• UI virtualization for 1000+ nodes
• Search and filtering functionality
• Sorting (Ascending, Descending, None)
• Performance optimization techniques

Customization and Styling

📄 Read: references/customization-styling.md

• Icon customization (expand/collapse, node icons)
• Dynamic icons based on data
• Text wrapping and display formatting
• CSS styling with e-icons classes
• Theme support and responsive design

Authorization and Security

📄 Read: references/authorization-authentication.md

• Authentication setup with AuthorizeView
• Role-based authorization and permissions
• Node-level access control
• Claims-based authorization patterns
• Securing edit operations and drag-drop

Navigation Patterns

📄 Read: references/navigation-patterns.md

• Node traversal methods (parent, children, siblings)
• Breadcrumb navigation implementation
• NavigateUrl property for node links
• Parent-child navigation relationships
• Deep-linking to specific nodes

Quick Links and Real-World Examples

Need help? Start with:

1. Quick Start - Get running in 5 minutes
2. Common Patterns - Copy-paste patterns for your use case
3. Key Properties - Find property details
4. data-binding.md - Learn data binding approaches
5. events-handling.md - Understand all events

Real-world implementations:

• File Browser: Use hierarchical data + expand-collapse + icons + drag-drop
• Organization Chart: Use data-binding + templates + multi-level navigation
• Navigation Menu: Use hierarchical data + keyboard navigation + load-on-demand
• Category Filter: Use self-referential data + checkboxes + filtering
• Permissions UI: Use checkboxes + AutoCheck + role-based authorization

Summary

This skill provides comprehensive guidance for implementing the Syncfusion Blazor TreeView component. Use the Documentation and Navigation Guide section above to find the specific reference file you need based on your use case.