syncfusion-blazor-dropdown-tree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Blazor Dropdown Tree Component

实现Syncfusion Blazor Dropdown Tree组件

The Blazor Dropdown Tree component is a hierarchical data selection control that displays tree-structured data in a dropdown popup. It supports local and remote data binding, single and multi-selection modes, checkboxes, filtering, custom templates, and comprehensive event handling.

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

When to Use This Skill

何时使用该技能

Display hierarchical data in a compact dropdown format
Single selection: Allow users to select one item from a tree structure (default mode)
Multi-selection: Enable selection of multiple tree nodes using CTRL+SHIFT shortcuts
Checkbox selection: Provide checkbox-based multi-selection with dependent state management
Filter tree data: Implement search functionality to filter nodes by text
Remote data sources: Bind to OData, OData V4, Web API, or custom service endpoints
Custom templates: Personalize item display, selected value display, and popup header
Handle events: Respond to lifecycle events, selection changes, popup actions
Form validation: Integrate with form validation frameworks
Styling and appearance: Apply CSS classes, disabled states, and theme customization

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

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and NuGet package setup
Web and Server app configuration
Basic component initialization
Data binding fundamentals
First working example

📄 阅读： references/getting-started.md

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

Selection and Modes

选择与模式

📄 Read: references/selection-and-modes.md

Single selection (default behavior)
Multi-selection with AllowMultiSelection property
Keyboard shortcuts (CTRL, SHIFT)
Preselected values and dynamic selection
Getting selected values with @bind-Value
Clearing selection

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

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

Checkbox Features

复选框功能

📄 Read: references/checkbox-features.md

ShowCheckBox property for multi-item selection
AutoUpdateCheckState for dependent parent-child relationships
ShowSelectAll for selecting/deselecting all nodes
SelectAllAsync and programmatic selection methods

📄 阅读： references/checkbox-features.md

启用ShowCheckBox属性实现多选
自动更新复选框状态（AutoUpdateCheckState），管理父子节点关联
显示全选复选框（ShowSelectAll），用于选中/取消所有节点
SelectAllAsync方法与程序化选择

Data Binding and Remote Data

数据绑定与远程数据

📄 Read: references/data-binding-operations.md

Local data binding (hierarchical and self-referential)
ExpandoObject and DynamicObject binding
Remote data with ODataAdaptor, ODataV4Adaptor, WebApiAdaptor
Entity Framework integration
Observable collections with dynamic data updates
Load on Demand for large datasets
Adding/removing items dynamically
GetTreeViewData method for retrieving node information

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

本地数据绑定（层级结构与自引用）
ExpandoObject与DynamicObject绑定
远程数据绑定，支持ODataAdaptor、ODataV4Adaptor、WebApiAdaptor
Entity Framework集成
可观察集合与动态数据更新
按需加载（LoadOnDemand）处理大型数据集
动态添加/删除项
使用GetTreeViewData方法获取节点信息

Events and Callbacks

事件与回调

📄 Read: references/events-callbacks.md

Lifecycle events (Created, Destroyed)
Popup events (OnPopupOpen, OnPopupClose)
Selection events (ValueChanging, ValueChanged)
Filtering event with custom filters
OnActionFailure for error handling
Event handlers and async support

📄 阅读： references/events-callbacks.md

生命周期事件（Created、Destroyed）
弹窗事件（OnPopupOpen、OnPopupClose）
选择事件（ValueChanging、ValueChanged）
过滤事件与自定义过滤器
OnActionFailure错误处理
事件处理程序与异步支持

Filtering and Search

过滤与搜索

📄 Read: references/filtering-search.md

AllowFiltering property to enable search
FilterType options (StartsWith, EndsWith, Contains)
IgnoreCase for case-insensitive filtering
FilterBarPlaceholder customization
Minimum filter length implementation

📄 阅读： references/filtering-search.md

启用AllowFiltering属性开启搜索功能
过滤类型选项（StartsWith、EndsWith、Contains）
IgnoreCase实现不区分大小写的过滤
自定义FilterBarPlaceholder占位符
最小过滤长度设置

Sorting

排序

📄 Read: references/sorting.md

SortOrder property (None, Ascending, Descending)
Dynamic sorting updates

📄 阅读： references/sorting.md

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

Templates and Customization

模板与定制

📄 Read: references/templates-customization.md

ItemTemplate for custom node rendering
ValueTemplate for selected value display
HeaderTemplate for popup header customization
Advanced styling and layout patterns

📄 阅读： references/templates-customization.md

ItemTemplate自定义节点渲染
ValueTemplate自定义选中值展示
HeaderTemplate自定义弹窗头部
高级样式与布局模式

Styling and Appearance

样式与外观

📄 Read: references/styling-appearance.md

Disabled state configuration
CssClass property with predefined classes (e-success, e-warning, e-error, e-outline)
PopupWidth and PopupHeight customization
ZIndex for layer management
Theme support and responsive design

📄 阅读： references/styling-appearance.md

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

Form Validation and Configuration

表单验证与配置

📄 Read: references/validation-localization.md

Form validation integration
Value binding in forms
Localization support
PopupSettings configuration
Accessibility and placeholder settings

📄 阅读： references/validation-localization.md

表单验证集成
表单中的值绑定
本地化支持
PopupSettings配置
可访问性与占位符设置

Quick Start Example

快速入门示例

razor

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

razor

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

Common Patterns

常见模式

Pattern 1: Multi-Selection with Checkboxes

模式1：带复选框的多选

Enable checkbox-based selection with automatic parent-child state management:

razor

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

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

razor

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

Pattern 2: Preselected Values

模式2：预选中值

Set default selected nodes using @bind-Value with AllowMultiSelection:

razor

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

结合AllowMultiSelection，使用@bind-Value设置默认选中节点：

razor

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

Pattern 3: Search with Filtering

模式3：带过滤的搜索

Enable search functionality with custom filter types:

razor

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

启用搜索功能，自定义过滤类型：

razor

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

Pattern 4: Remote Data Binding (OData)

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

Bind to remote OData services with DataManager:

razor

<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="https://services.odata.org/V4/Northwind/Northwind.svc" 
            Adaptor="Syncfusion.Blazor.Adaptors.ODataV4Adaptor" 
            CrossDomain="true">
        </SfDataManager>
    </DropDownTreeField>
</SfDropDownTree>

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

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

razor

<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="https://services.odata.org/V4/Northwind/Northwind.svc" 
            Adaptor="Syncfusion.Blazor.Adaptors.ODataV4Adaptor" 
            CrossDomain="true">
        </SfDataManager>
    </DropDownTreeField>
</SfDropDownTree>

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

Key Properties and APIs

核心属性与API

Property	Type	Description
`TItem`	Generic	Model class for data items
`TValue`	Generic	Type of selected value(s)
`Value`	List<TValue>	Two-way bindable selected values
`DataSource`	IEnumerable	Local data source (via DropDownTreeField)
`AllowMultiSelection`	bool	Enable multi-node selection
`ShowCheckBox`	bool	Display checkboxes for selection
`AutoUpdateCheckState`	bool	Auto-sync parent-child checkbox states
`ShowSelectAll`	bool	Display select/deselect all checkbox
`AllowFiltering`	bool	Enable search filtering
`FilterType`	FilterType	Filter matching strategy (StartsWith, EndsWith, Contains)
`IgnoreCase`	bool	Case-insensitive filtering
`LoadOnDemand`	bool	Lazy-load child nodes on expand
`Placeholder`	string	Input placeholder text
`Width`	string	Component width
`PopupWidth`	string	Dropdown popup width
`PopupHeight`	string	Dropdown popup height
`ZIndex`	int	CSS z-index of popup
`CssClass`	string	Custom CSS classes
`Disabled`	bool	Disable component interaction

属性	类型	描述
`TItem`	泛型	数据项的模型类
`TValue`	泛型	选中值的类型
`Value`	List<TValue>	双向绑定的选中值
`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层级
`CssClass`	string	自定义CSS类
`Disabled`	bool	禁用组件交互

Key Events

核心事件

Created: Component initialization complete
Destroyed: Component destruction
OnPopupOpen: Popup opened after animation
OnPopupClose: Popup closed after animation
ValueChanging: Before value change (DdtChangeEventArgs<TValue>)
ValueChanged: After value change (List<TValue>)
Filtering: Search text entered (DdtFilteringEventArgs)
OnActionFailure: Error during data operations

Created：组件初始化完成
Destroyed：组件销毁
OnPopupOpen：弹窗动画完成后打开
OnPopupClose：弹窗动画完成后关闭
ValueChanging：值变更前触发（参数为DdtChangeEventArgs<TValue>）
ValueChanged：值变更后触发（参数为List<TValue>）
Filtering：输入搜索文本时触发（参数为DdtFilteringEventArgs）
OnActionFailure：数据操作出错时触发

Key Methods

核心方法

SelectAllAsync(): Programmatically select all nodes
SelectAllAsync(false): Programmatically deselect all nodes
ClearAsync(): Clear all selected values
GetTreeViewData(id): Get node information by ID

SelectAllAsync()：程序化选中所有节点
SelectAllAsync(false)：程序化取消选中所有节点
ClearAsync()：清除所有选中值
GetTreeViewData(id)：通过ID获取节点信息