syncfusion-blazor-dropdown-tree

实现 Syncfusion Blazor Dropdown Tree 组件

Blazor Dropdown Tree 组件是一种分层数据选择控件，可在下拉弹出窗口中显示树形结构的数据。它支持本地和远程数据绑定、单选和多选模式、复选框、筛选、自定义模板以及全面的事件处理。

何时使用此技能

• 显示分层数据：以紧凑的下拉格式显示分层数据
• 单选：允许用户从树形结构中选择一个项目（默认模式）
• 多选：支持用户使用 CTRL+SHIFT 快捷键选择多个树节点
• 复选框选择：提供基于复选框的多选，并管理关联状态
• 筛选树形数据：实现按文本筛选节点的搜索功能
• 远程数据源：绑定到 OData、OData V4、Web API 或自定义服务端点
• 自定义模板：自定义项目显示、所选值显示和弹出窗口标题
• 处理事件：响应生命周期事件、选择变更和弹出窗口操作
• 表单验证：与表单验证框架集成
• 样式和外观：应用 CSS 类、禁用状态和主题自定义

文档和导航指南

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• Web 和 Server 应用配置
• 基本组件初始化
• 数据绑定基础
• 第一个可运行示例

选择和模式

📄 阅读： references/selection-and-modes.md

• 单选（默认行为）
• 使用 AllowMultiSelection 属性启用多选
• 键盘快捷键（CTRL、SHIFT）
• 预选值和动态选择
• 使用 @bind-Value 获取所选值
• 清除选择

复选框功能

📄 阅读： references/checkbox-features.md

• 使用 ShowCheckBox 属性选择多个项目
• 使用 AutoUpdateCheckState 管理父子节点的关联状态
• 使用 ShowSelectAll 选择或取消选择所有节点
• SelectAllAsync 和程序化选择方法

数据绑定和远程数据

📄 阅读： references/data-binding-operations.md

• 本地数据绑定（分层和自引用）
• ExpandoObject 和 DynamicObject 绑定
• 使用 ODataAdaptor、ODataV4Adaptor、WebApiAdaptor 绑定远程数据
• Entity Framework 集成
• 使用可观察集合动态更新数据
• 为大型数据集启用按需加载
• 动态添加或移除项目
• 使用 GetTreeViewData 方法获取节点信息

事件和回调

📄 阅读： references/events-callbacks.md

• 生命周期事件（Created、Destroyed）
• 弹出窗口事件（OnPopupOpen、OnPopupClose）
• 选择事件（ValueChanging、ValueChanged）
• 使用自定义筛选器的筛选事件
• 使用 OnActionFailure 处理错误
• 事件处理程序和异步支持

筛选和搜索

📄 阅读： references/filtering-search.md

• 使用 AllowFiltering 属性启用搜索
• FilterType 选项（StartsWith、EndsWith、Contains）
• 使用 IgnoreCase 进行不区分大小写的筛选
• 自定义 FilterBarPlaceholder
• 实现最小筛选长度

排序

📄 阅读： references/sorting.md

• SortOrder 属性（None、Ascending、Descending）
• 动态更新排序

模板和自定义

📄 阅读： references/templates-customization.md

• 使用 ItemTemplate 自定义节点呈现方式
• 使用 ValueTemplate 显示所选值
• 使用 HeaderTemplate 自定义弹出窗口标题
• 高级样式和布局模式

样式和外观

📄 阅读： references/styling-appearance.md

• 禁用状态配置
• CssClass 属性及预定义类（e-success、e-warning、e-error、e-outline）
• 自定义 PopupWidth 和 PopupHeight
• 使用 ZIndex 管理图层
• 主题支持和响应式设计

表单验证和配置

📄 阅读： references/validation-localization.md

• 集成表单验证
• 表单中的值绑定
• 本地化支持
• PopupSettings 配置
• 无障碍功能和占位符设置

快速入门示例

@using Syncfusion.Blazor.Navigations

<SfDropDownTree TItem="EmployeeData" TValue="string" 
    Placeholder="Select an employee" 
    Width="500px">
    <DropDownTreeField TItem="EmployeeData" 
        DataSource="Data" 
        ID="Id" 
        Text="Name" 
        HasChildren="HasChild" 
        ParentID="PId">
    </DropDownTreeField>
</SfDropDownTree>

@code {
    List<EmployeeData> Data = new List<EmployeeData>
    {
        new EmployeeData() { Id = "1", Name = "Steven Buchanan", Job = "General Manager", HasChild = true, Expanded = true },
        new EmployeeData() { Id = "2", PId = "1", Name = "Laura Callahan", Job = "Product Manager", HasChild = true },
        new EmployeeData() { Id = "3", PId = "2", Name = "Andrew Fuller", Job = "Team Lead", HasChild = true },
        new EmployeeData() { Id = "4", PId = "3", Name = "Anne Dodsworth", Job = "Developer" },
    };

    public class EmployeeData
    {
        public string? Id { get; set; }
        public string? Name { get; set; }
        public string? Job { get; set; }
        public bool HasChild { get; set; }
        public bool Expanded { get; set; }
        public string? PId { get; set; }
    }
}

常见模式

模式 1：使用复选框进行多选

启用基于复选框的选择，并自动管理父子节点状态：

<SfDropDownTree TItem="EmployeeData" TValue="string" 
    ShowCheckBox="true" 
    AutoUpdateCheckState="true"
    ShowSelectAll="true">
    <DropDownTreeField TItem="EmployeeData" DataSource="Data" 
        ID="Id" Text="Name" HasChildren="HasChild" ParentID="PId">
    </DropDownTreeField>
</SfDropDownTree>

模式 2：预选值

使用 @bind-Value 和 AllowMultiSelection 设置默认选中的节点：

<SfDropDownTree TItem="EmployeeData" TValue="string" 
    AllowMultiSelection="true"
    @bind-Value="@SelectedIds">
    <DropDownTreeField TItem="EmployeeData" DataSource="Data" 
        ID="Id" Text="Name" HasChildren="HasChild" ParentID="PId">
    </DropDownTreeField>
</SfDropDownTree>

@code {
    List<string> SelectedIds = new List<string>() { "1", "5" };
}

模式 3：使用筛选功能进行搜索

使用自定义筛选类型启用搜索功能：

<SfDropDownTree TItem="EmployeeData" TValue="string" 
    AllowFiltering="true"
    FilterType="FilterType.Contains"
    FilterBarPlaceholder="Search employees...">
    <DropDownTreeField TItem="EmployeeData" DataSource="Data" 
        ID="Id" Text="Name" HasChildren="HasChild" ParentID="PId">
    </DropDownTreeField>
</SfDropDownTree>

模式 4：远程数据绑定（OData）

使用 DataManager 绑定到远程 OData 服务：

<SfDropDownTree TValue="int?" TItem="TreeData" Placeholder="Select an employee" Width="500px">
    <DropDownTreeField TItem="TreeData" Query="@Query" 
        ID="EmployeeID" Text="FirstName" ParentID="ReportsTo" HasChildren="HasChildren">
        <SfDataManager Url="url" 
            Adaptor="Syncfusion.Blazor.Adaptors.ODataV4Adaptor" 
            CrossDomain="true">
        </SfDataManager>
    </DropDownTreeField>
</SfDropDownTree>

@code {
    public Query Query = new Query();
}

关键属性和 API

属性	类型	描述
TItem	泛型	数据项的模型类
TValue	泛型	所选值的类型
Value	List	可双向绑定的所选值
DataSource	IEnumerable	本地数据源（通过 DropDownTreeField）
AllowMultiSelection	bool	启用多节点选择
ShowCheckBox	bool	显示用于选择的复选框
AutoUpdateCheckState	bool	自动同步父子复选框状态
ShowSelectAll	bool	显示全选/取消全选复选框
AllowFiltering	bool	启用搜索筛选
FilterType	FilterType	筛选匹配策略（StartsWith、EndsWith、Contains）
IgnoreCase	bool	筛选时忽略大小写
LoadOnDemand	bool	展开时延迟加载子节点
Placeholder	string	输入占位文本
Width	string	组件宽度
PopupWidth	string	下拉弹出框宽度
PopupHeight	string	下拉弹出框高度
ZIndex	int	弹出框的 CSS z-index
CssClass	string	自定义 CSS 类
Disabled	bool	禁用组件交互

关键事件

• Created：组件初始化完成
• Destroyed：组件销毁
• OnPopupOpen：弹出框动画结束后打开
• OnPopupClose：弹出框动画结束后关闭
• ValueChanging：值更改前（DdtChangeEventArgs）
• ValueChanged：值更改后（List）
• Filtering：输入搜索文本时（DdtFilteringEventArgs）
• OnActionFailure：数据操作期间发生错误

关键方法

• SelectAllAsync()：以编程方式选择所有节点
• SelectAllAsync(false)：以编程方式取消选择所有节点
• ClearAsync()：清除所有所选值
• GetTreeViewData(id)：按 ID 获取节点信息