syncfusion-blazor-treeview

Name: syncfusion-blazor-treeview
Author: syncfusion

github.com/syncfusion设计与 UI4371 次安装1 周前更新

代码仓库

关于 syncfusion-blazor-treeview

该技能为 Blazor 开发者提供 Syncfusion TreeView 的实现参考，用于展示和操作层级数据。内容覆盖数据绑定、节点选择与编辑、拖放、筛选及大型数据集虚拟化。

主要功能

01绑定本地或远程数据源
02支持单选、多选及复选框
03编辑节点并拖放调整层级
04筛选搜索与按需加载
05大型数据集虚拟滚动

适用场景

01构建带拖放功能的文件浏览器
02制作组织结构与层级导航
03创建分类筛选或权限界面

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/syncfusion/blazor-ui-components-skills --skill syncfusion-blazor-treeview

安装后在 Claude Code 中输入/syncfusion-blazor-treeview确认已加载。

包含的文件

除 SKILL.md 外，安装时一起下载的参考资料和脚本。

references/

advanced-features.md

authorization-authentication.md

checkbox-features.md

customization-styling.md

data-binding.md

events-handling.md

expand-collapse-actions.md

getting-started.md

navigation-patterns.md

node-editing.md

node-selection.md

详细介绍

实现 Syncfusion Blazor TreeView 组件

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

适用场景

在需要以下功能时使用 TreeView 组件：

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

安装与设置

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

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

快速入门

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

关键属性

属性	类型	默认值	用途
`AllowDragAndDrop`	bool	false	启用/禁用拖放层级排序
`AllowEditing`	bool	false	允许双击重命名节点
`AllowMultiSelection`	bool	false	启用 Ctrl+Click 多选
`ShowCheckBox`	bool	false	为每个节点显示复选框
`AutoCheck`	bool	true	选中父节点时自动选中/取消选中子节点
`EnablePersistence`	bool	false	将展开/选中/勾选状态保存到 localStorage
`EnableVirtualization`	bool	false	为 1000+ 个节点启用虚拟滚动（需要设置 Height）
`ExpandedNodes`	string[]	Empty	初始展开的节点 ID（支持双向绑定）
`SelectedNodes`	string[]	Empty	已选中节点的 ID（支持双向绑定）
`CheckedNodes`	string[]	Empty	已勾选节点的 ID（支持双向绑定）
`LoadOnDemand`	bool	true	仅在节点展开时加载其子节点
`ExpandOn`	ExpandAction	Click	通过 Click/DoubleClick/None 触发展开
`Height`	string	"auto"	固定高度（虚拟化所必需）

关键方法

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

关键事件

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

常见模式

模式 1：基本选择

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

模式 2：多选

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

模式 3：按需加载

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

模式 4：拖放

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

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

模式 5：节点编辑

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

模式 6：复选框

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

var checked = treeRef.GetAllCheckedNodes();