syncfusion-blazor-treeview

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Blazor TreeView Component

实现Syncfusion Blazor TreeView组件

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.

Blazor TreeView组件以可展开/折叠的树形结构显示层级数据。它支持本地和远程数据绑定、单选和多选、编辑、复选框、拖拽重排序、大数据集虚拟化、筛选以及全面的事件处理。

📋 Table of Contents

适用场景
安装与配置
快速开始
关键属性
关键方法
关键事件
常见模式
完整参考导航

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

在以下场景中使用TreeView组件：

显示层级数据：以树形结构展示可展开/折叠的节点
单选：允许用户从树形中选择单个节点
多选：支持通过Ctrl+点击和Shift+点击选择多个树形节点
复选框选择：提供基于复选框的多选功能，并自动管理父子节点状态
编辑节点：允许在线重命名或编辑节点文本
拖拽：支持在层级结构内重新排序节点
筛选与搜索：实现节点搜索功能
远程数据源：绑定到Web API、OData服务或自定义端点
事件处理：响应展开、折叠、选择、编辑和拖拽操作
虚拟化：流畅滚动显示大数据集（1000+节点）
自定义样式：为节点应用图标、颜色和模板

Installation & Setup

安装与配置

Install Syncfusion NuGet packages and configure your Blazor project:

csharp

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

安装Syncfusion NuGet包并配置Blazor项目：

csharp

// 1. 安装NuGet包
// Install-Package Syncfusion.Blazor.Navigations -Version 26.1.35
// Install-Package Syncfusion.Blazor.Themes -Version 26.1.35

// 2. 添加到_Imports.razor
@using Syncfusion.Blazor
@using Syncfusion.Blazor.Navigations

// 3. 在Program.cs中注册服务
builder.Services.AddSyncfusionBlazor();

// 4. 在Index.html或_Layout.cshtml中添加CSS主题
<link href="_content/Syncfusion.Blazor.Themes/bootstrap5.css" rel="stylesheet" />

Quick Start

快速开始

csharp

@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() }
    };
}

csharp

@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

关键属性

Property	Type	Default	Purpose
`AllowDragAndDrop`	bool	false	Enable/disable drag-drop hierarchy reordering
`AllowEditing`	bool	false	Allow double-click node renaming
`AllowMultiSelection`	bool	false	Enable Ctrl+Click multi-selection
`ShowCheckBox`	bool	false	Display checkboxes for each node
`AutoCheck`	bool	true	Auto-check/uncheck children when parent checked
`EnablePersistence`	bool	false	Persist expanded/selected/checked state to localStorage
`EnableVirtualization`	bool	false	Virtual scrolling for 1000+ nodes (requires Height)
`ExpandedNodes`	string[]	Empty	Initially expanded node IDs (2-way bindable)
`SelectedNodes`	string[]	Empty	Selected node IDs (2-way bindable)
`CheckedNodes`	string[]	Empty	Checked node IDs (2-way bindable)
`LoadOnDemand`	bool	true	Load children only when node expands
`ExpandOn`	ExpandAction	Click	Trigger expand on Click/DoubleClick/None
`Height`	string	"auto"	Fixed height (required for virtualization)

属性	类型	默认值	用途
`AllowDragAndDrop`	bool	false	启用/禁用拖拽重排序层级结构
`AllowEditing`	bool	false	允许双击节点重命名
`AllowMultiSelection`	bool	false	启用Ctrl+点击多选
`ShowCheckBox`	bool	false	为每个节点显示复选框
`AutoCheck`	bool	true	当父节点被勾选时自动勾选/取消勾选子节点
`EnablePersistence`	bool	false	将展开/选中/勾选状态持久化到localStorage
`EnableVirtualization`	bool	false	为1000+节点提供虚拟滚动（需要设置Height）
`ExpandedNodes`	string[]	空数组	初始展开的节点ID（支持双向绑定）
`SelectedNodes`	string[]	空数组	选中的节点ID（支持双向绑定）
`CheckedNodes`	string[]	空数组	勾选的节点ID（支持双向绑定）
`LoadOnDemand`	bool	true	仅当节点展开时加载子节点
`ExpandOn`	ExpandAction	Click	触发展开的方式：点击/双击/无
`Height`	string	"auto"	固定高度（虚拟化功能必需）

Key Methods

关键方法

Method	Purpose
`ExpandAllAsync()`	Expand all nodes
`ExpandAllAsync(string[] nodeIds)`	Expand specific nodes by ID
`CollapseAllAsync()`	Collapse all nodes
`CollapseAllAsync(string[] nodeIds)`	Collapse specific nodes
`BeginEditAsync(string nodeId)`	Enter edit mode for a node
`GetTreeData()`	Get all tree data
`GetTreeData(string nodeId)`	Get specific node data by ID
`EnsureVisibleAsync(string nodeId)`	Scroll to make node visible
`CheckAllAsync()`	Check all checkboxes
`UncheckAllAsync()`	Uncheck all checkboxes
`ClearStateAsync()`	Clear all state (selection, expand, check)

方法	用途
`ExpandAllAsync()`	展开所有节点
`ExpandAllAsync(string[] nodeIds)`	根据ID展开指定节点
`CollapseAllAsync()`	折叠所有节点
`CollapseAllAsync(string[] nodeIds)`	折叠指定节点
`BeginEditAsync(string nodeId)`	进入指定节点的编辑模式
`GetTreeData()`	获取所有树形数据
`GetTreeData(string nodeId)`	根据ID获取指定节点数据
`EnsureVisibleAsync(string nodeId)`	滚动到节点使其可见
`CheckAllAsync()`	勾选所有复选框
`UncheckAllAsync()`	取消勾选所有复选框
`ClearStateAsync()`	清除所有状态（选择、展开、勾选）

Key Events

关键事件

Event	Fires When	Common Uses
`Created`	TreeView initialized	Post-initialization setup, load preferences
`DataBound`	Data binding complete	Auto-expand default nodes, validate data
`NodeSelected`	Node left-clicked	Load node details, enable actions
`NodeClicked`	Node clicked	Distinguish single vs double-click
`NodeExpanded`	Node expanded	Load child nodes (load-on-demand)
`NodeCollapsed`	Node collapsed	Optional: Unload children from memory
`NodeEditing`	Before edit mode	Validate permissions, prevent edits
`NodeEdited`	Edit confirmed	Validate new text, save to server
`OnNodeDragStart`	Drag begins	Prevent dragging restricted nodes
`NodeDropped`	Drop completed	Update hierarchy in server
`NodeChecking`	Before checkbox changes	Prevent checking restricted nodes
`NodeChecked`	Checkbox changed	Update related data, trigger actions
`DataSourceChanged`	Data source updated	Re-apply filters, refresh calculations
`OnActionFailure`	Action fails (API error)	Recover from errors, show notifications
`OnKeyPress`	Key pressed	Implement keyboard shortcuts (Delete, F2, etc)

事件	触发时机	常见用途
`Created`	TreeView初始化完成后	初始化后设置、加载偏好设置
`DataBound`	数据绑定完成后	自动展开默认节点、验证数据
`NodeSelected`	节点被左键点击时	加载节点详情、启用相关操作
`NodeClicked`	节点被点击时	区分单击与双击操作
`NodeExpanded`	节点被展开时	加载子节点（按需加载）
`NodeCollapsed`	节点被折叠时	可选：从内存中卸载子节点
`NodeEditing`	进入编辑模式前	验证权限、阻止编辑
`NodeEdited`	编辑确认后	验证新文本、保存到服务器
`OnNodeDragStart`	拖拽开始时	阻止拖拽受限制的节点
`NodeDropped`	拖拽完成时	更新服务器端的层级结构
`NodeChecking`	复选框状态改变前	阻止勾选受限制的节点
`NodeChecked`	复选框状态改变后	更新相关数据、触发操作
`DataSourceChanged`	数据源更新后	重新应用筛选、刷新计算结果
`OnActionFailure`	操作失败时（API错误）	错误恢复、显示通知
`OnKeyPress`	按键被按下时	实现键盘快捷键（删除、F2等）

Common Patterns

常见模式

Pattern 1: Basic Selection

模式1：基础选择

csharp

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

csharp

<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

模式2：多选

csharp

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

csharp

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

Pattern 3: Load on Demand

模式3：按需加载

csharp

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

csharp

void OnNodeExpanded(NodeExpandEventArgs args)
{
    if (args.NodeData.HasChild && args.NodeData.Child == null)
    {
        // 从API加载子节点
        args.NodeData.Child = await FetchChildren(args.NodeData.Id);
    }
}

Pattern 4: Drag and Drop

模式4：拖拽

csharp

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

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

csharp

<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

模式5：节点编辑

csharp

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

csharp

<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

模式6：复选框

csharp

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

var checked = treeRef.GetAllCheckedNodes();

csharp

<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

📄 阅读： references/getting-started.md

安装与NuGet包配置
按项目类型配置（WebAssembly、Server、Web App、MAUI）
CSS主题配置
服务注册与第一个TreeView组件

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

📄 阅读： references/data-binding.md

本地数据绑定（层级结构和自引用结构）
使用OData、OData V4和Web API适配器的远程数据
大数据集的按需加载
TreeViewFieldsSettings属性映射
数据绑定完成后的DataBound事件

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

📄 阅读： references/node-selection.md

单节点选择（默认行为）
使用AllowMultiSelection属性启用多选
通过NodeSelected事件访问选中节点数据
使用SelectedNodes绑定实现程序化选择
选择验证与条件选择

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

📄 阅读： references/expand-collapse-actions.md

展开/折叠方法（ExpandAllAsync、CollapseAllAsync）
ExpandedNodes双向绑定实现程序化控制
通过数据源设置初始展开状态
使用TreeViewNodeAnimationSettings实现展开/折叠动画
通过NodeExpanded事件按需加载子节点

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

📄 阅读： references/node-editing.md

使用AllowEditing属性启用编辑
双击进入编辑模式
使用BeginEditAsync方法程序化进入编辑模式
NodeEditing和NodeEdited事件用于验证
重命名操作与冲突检测

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

📄 阅读： references/checkbox-features.md

使用ShowCheckBox属性实现多项目选择
AutoCheck自动同步父子节点状态
CheckedNodes双向绑定实现程序化控制
获取勾选节点并进行筛选和遍历
基于权限和角色的复选框模式

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)

📄 阅读： references/events-handling.md

生命周期事件（Created、DataBound）
选择事件（NodeSelected、SelectedNodesChanged）
展开/折叠事件（NodeExpanded、NodeCollapsed）
编辑事件（NodeEditing、NodeEdited）
复选框事件（NodeChecking、NodeChecked）
拖拽事件（OnNodeDragStart、NodeDropped）
键盘快捷键（回车、删除、F2、方向键）

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

📄 阅读： references/advanced-features.md

拖拽与层级重排序
1000+节点的UI虚拟化
搜索与筛选功能
排序（升序、降序、无）
性能优化技巧

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

📄 阅读： references/customization-styling.md

图标自定义（展开/折叠、节点图标）
基于数据的动态图标
文本换行与显示格式
使用e-icons类进行CSS样式设置
主题支持与响应式设计

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

📄 阅读： references/authorization-authentication.md

使用AuthorizeView进行身份验证设置
基于角色的授权与权限
节点级别的访问控制
基于声明的授权模式
保护编辑操作与拖拽功能

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

📄 阅读： references/navigation-patterns.md

节点遍历方法（父节点、子节点、兄弟节点）
面包屑导航实现
使用NavigateUrl属性设置节点链接
父子节点导航关系
跳转到特定节点的深度链接

Quick Links and Real-World Examples

快速链接与实际场景示例

Need help? Start with:

Quick Start - Get running in 5 minutes
Common Patterns - Copy-paste patterns for your use case
Key Properties - Find property details
data-binding.md - Learn data binding approaches
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

需要帮助？ 从以下内容开始：

快速开始 - 5分钟内快速上手
常见模式 - 复制粘贴即可使用的场景代码
关键属性 - 查找属性详细信息
data-binding.md - 学习数据绑定方法
events-handling.md - 了解所有事件

实际场景实现：

文件浏览器：使用层级数据 + 展开折叠 + 图标 + 拖拽
组织架构图：使用数据绑定 + 模板 + 多级导航
导航菜单：使用层级数据 + 键盘导航 + 按需加载
分类筛选器：使用自引用数据 + 复选框 + 筛选
权限UI：使用复选框 + AutoCheck + 基于角色的授权

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.

本技能提供了实现Syncfusion Blazor TreeView组件的全面指南。根据你的使用场景，使用上方的文档与导航指南部分查找所需的具体参考文件。