syncfusion-aspnetcore-dropdown-tree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion DropDownTree Component

实现Syncfusion DropDownTree组件

The Syncfusion DropDownTree control is a dropdown component that displays hierarchical tree data structures, allowing users to select single or multiple values from a tree hierarchy. It combines the features of a traditional dropdown list with the hierarchical organization of a tree structure, making it ideal for applications requiring organized, nested data selection.

Syncfusion DropDownTree控件是一款下拉组件，用于展示层级树形数据结构，允许用户从树形层级中选择单个或多个值。它结合了传统下拉列表的特性与树形结构的层级组织方式，非常适合需要有序嵌套数据选择的应用场景。

When to Use This Skill

何时使用该技能

Use this skill when you need to:

Display hierarchical data in a dropdown format where items have parent-child relationships
Enable tree-based selection with expand/collapse node functionality
Support multi-selection with checkbox or keyboard navigation
Implement custom templates for item display, headers, footers, and selected value representation
Bind data from local JavaScript arrays, remote servers (OData, Web API), or lazy-load on demand
Maintain accessibility with keyboard support (arrow keys, Enter, Space) and ARIA attributes
Localize the component for different cultures and languages
Prevent node selection for parent nodes while allowing child selection

在以下场景中使用该技能：

展示层级数据：以下拉格式显示具有父子关系的项
启用基于树形的选择：具备展开/折叠节点功能
支持多选：通过复选框或键盘导航实现
实现自定义模板：用于项展示、页眉、页脚以及选中值的呈现
绑定数据：支持本地JavaScript数组、远程服务器（OData、Web API）或按需懒加载
维护可访问性：支持键盘操作（箭头键、Enter、Space）和ARIA属性
组件本地化：适配不同文化和语言
禁止父节点选择：仅允许子节点被选择

Key Features Overview

核心功能概述

The DropDownTree component provides comprehensive functionality for tree-based dropdown selection:

Data Binding Options: Hierarchical data, self-referential data structures, remote data services with DataManager adaptors
Selection Modes: Single selection, multi-selection with checkboxes, delimiter-separated display, chip/box mode, or custom templates
Keyboard Navigation: Full keyboard support with arrow keys, Enter, Space, Home, End, Alt+Up/Down, Escape
Custom Templates: Item templates, value templates, header templates, footer templates, no-records templates, action-failure templates
Tree Configuration: Expand behavior (click, double-click, auto), load on demand (lazy loading), auto-check parent-child dependencies
Accessibility: WAI-ARIA compliant with listbox roles, treeitem roles, ARIA attributes, screen reader support
Filtering: Real-time search with configurable filter types (StartsWith, EndsWith, Contains), case sensitivity, accent handling
Persistence: State retention across browser sessions
RTL Support: Right-to-left rendering for Arabic, Hebrew, and other RTL languages

DropDownTree组件为基于树形的下拉选择提供了全面的功能：

数据绑定选项：层级数据、自引用数据结构、搭配DataManager适配器的远程数据服务
选择模式：单选、带复选框的多选、分隔符分隔显示、芯片/框模式或自定义模板
键盘导航：完整的键盘支持，包括箭头键、Enter、Space、Home、End、Alt+上下键、Escape
自定义模板：项模板、值模板、页眉模板、页脚模板、无数据模板、操作失败模板
树形配置：展开行为（点击、双击、自动）、按需加载（懒加载）、父子依赖自动勾选
可访问性：符合WAI-ARIA标准，具备列表框角色、树项角色、ARIA属性，支持屏幕阅读器
过滤功能：实时搜索，可配置过滤类型（开头匹配、结尾匹配、包含匹配），支持大小写敏感设置、重音处理
状态持久化：跨浏览器会话保留状态
RTL支持：支持阿拉伯语、希伯来语等RTL语言的从右到左渲染

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Platform setup and prerequisites
NuGet package installation
Script and stylesheet references
Tag helper configuration
Basic DropDownTree initialization
First rendering example with data binding
Building blocks needed before advanced features

📄 阅读： references/getting-started.md

平台设置与前置要求
NuGet包安装
脚本与样式表引用
标签助手配置
基础DropDownTree初始化
带数据绑定的首次渲染示例
高级功能所需的基础构建块

Data Binding and Hierarchy

数据绑定与层级结构

📄 Read: references/data-binding.md

Hierarchical data source binding with nested array structures
Self-referential data structures with parent-value relationships
Remote data binding with DataManager and adaptors (OData, ODataV4, WebAPI, URL)
Load on demand (lazy loading) for large datasets
Field mapping configuration (text, value, child, parentValue, hasChildren)
Query support for remote data filtering
Preventing node selection with the selectable property

📄 阅读： references/data-binding.md

嵌套数组结构的层级数据源绑定
带父值关系的自引用数据结构
搭配DataManager和适配器（OData、ODataV4、WebAPI、URL）的远程数据绑定
大型数据集的按需加载（懒加载）
字段映射配置（text、value、child、parentValue、hasChildren）
远程数据过滤的查询支持
通过selectable属性禁止节点选择

Selection and Checkbox Features

选择与复选框功能

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

Enabling checkbox mode with showCheckBox property
Multi-selection with allowMultiSelection property
Auto-check dependency with parent-child synchronization
Select All functionality in popup header
Display modes (Default, Delimiter, Box, Custom) for selected items
Custom template for selected item representation
Check state management and prevention for disabled children
Controlling expand behavior and tree interaction modes

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

通过showCheckBox属性启用复选框模式
通过allowMultiSelection属性启用多选
父子同步的自动勾选依赖
弹出框页眉的全选功能
选中项的显示模式（默认、分隔符、框、自定义）
选中项呈现的自定义模板
禁用子项的勾选状态管理与禁止
控制展开行为与树形交互模式

Templates and Customization

模板与自定义

📄 Read: references/templates-and-customization.md

Item template for customizing list item appearance
Value template for customizing selected value display
Header template for popup header customization
Footer template for popup footer customization
No records template for empty search results
Action failure template for remote data errors
Custom template modes (Default, Delimiter, Box, Custom) for multi-selection display
CSS class customization and HTML attribute mapping
Styling and visual customization techniques

📄 阅读： references/templates-and-customization.md

用于自定义列表项外观的项模板
用于自定义选中值显示的值模板
用于自定义弹出框页眉的页眉模板
用于自定义弹出框页脚的页脚模板
空搜索结果的无数据模板
远程数据加载失败的操作失败模板
多选显示的自定义模板模式（默认、分隔符、框、自定义）
CSS类自定义与HTML属性映射
样式与视觉自定义技巧

Properties and Configuration

属性与配置

📄 Read: references/properties-and-configuration.md

Complete property reference including filtering, appearance, behavior, data settings
Expand behavior configuration (Auto, Click, DblClick, None)
Filter types and filter bar customization
Float label types and placeholder text
Persistence and state management
RTL and locale settings
Icon CSS and image URL mapping
HTML attributes and CSS class application
Destruction behavior when popup closes

📄 阅读： references/properties-and-configuration.md

完整的属性参考，包括过滤、外观、行为、数据设置
展开行为配置（Auto、Click、DblClick、None）
过滤类型与过滤栏自定义
浮动标签类型与占位文本
持久化与状态管理
RTL与区域设置
图标CSS与图片URL映射
HTML属性与CSS类应用
弹出框关闭时的销毁行为

Events and Interactions

事件与交互

📄 Read: references/events-and-interactions.md

Change event and value tracking
Selection events (select/unselect actions)
Before open/popup events for preventing or customizing popup display
Data bound event for remote data completion
Filtering event for custom filter implementation
Keyboard interaction event handling
Focus and blur events for state management
Event arguments and properties available in handlers

📄 阅读： references/events-and-interactions.md

变更事件与值跟踪
选择事件（选中/取消选中操作）
弹出框打开前的事件，用于阻止或自定义弹出框显示
远程数据绑定完成的数据绑定事件
用于自定义过滤实现的过滤事件
键盘交互事件处理
用于状态管理的聚焦与失焦事件
事件处理程序中可用的事件参数与属性

Accessibility and Globalization

可访问性与全球化

📄 Read: references/accessibility-and-globalization.md

Keyboard navigation shortcuts and interaction patterns
ARIA attributes and WAI-ARIA compliance
Screen reader support and accessible markup
Focus management and keyboard event handling
Localization and culture-specific text customization
RTL (right-to-left) language support
Multi-language string customization
Accessibility best practices for dropdown trees

📄 阅读： references/accessibility-and-globalization.md

键盘导航快捷键与交互模式
ARIA属性与WAI-ARIA合规性
屏幕阅读器支持与可访问标记
焦点管理与键盘事件处理
本地化与特定文化文本自定义
RTL（从右到左）语言支持
多语言字符串自定义
下拉树形组件的可访问性最佳实践

Quick Start Example

快速入门示例

Basic Initialization

基础初始化

html

<!-- ASP.NET Core Razor Template -->
@{
    var treeData = new List<TreeNode>
    {
        new TreeNode { Id = "1", Text = "Item 1" },
        new TreeNode { Id = "2", Text = "Item 2", Children = new List<TreeNode>
        {
            new TreeNode { Id = "3", Text = "Child 1" },
            new TreeNode { Id = "4", Text = "Child 2" }
        }}
    };
}

<ejs-dropdowntree id="tree" placeholder="Select an item">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

html

<!-- ASP.NET Core Razor Template -->
@{
    var treeData = new List<TreeNode>
    {
        new TreeNode { Id = "1", Text = "Item 1" },
        new TreeNode { Id = "2", Text = "Item 2", Children = new List<TreeNode>
        {
            new TreeNode { Id = "3", Text = "Child 1" },
            new TreeNode { Id = "4", Text = "Child 2" }
        }}
    };
}

<ejs-dropdowntree id="tree" placeholder="Select an item">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

With Checkbox Support

带复选框支持

html

<ejs-dropdowntree id="treeCheckbox" showCheckBox="true">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

html

<ejs-dropdowntree id="treeCheckbox" showCheckBox="true">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

With Templates

带模板

html

@{
    var itemTemp = "<span>${Text} (${Id})</span>";
    var valueTemp = "<span>Selected: ${Text}</span>";
}

<ejs-dropdowntree id="treeTemplate" itemTemplate="@itemTemp" valueTemplate="@valueTemp">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

html

@{
    var itemTemp = "<span>${Text} (${Id})</span>";
    var valueTemp = "<span>Selected: ${Text}</span>";
}

<ejs-dropdowntree id="treeTemplate" itemTemplate="@itemTemp" valueTemplate="@valueTemp">
    <e-dropdowntree-fields dataSource="@treeData" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

Common Patterns

常见模式

Pattern 1: Hierarchical Organization Categories

模式1：层级组织分类

Scenario: Display product categories in a hierarchical structure

html

<ejs-dropdowntree id="categories" placeholder="Select Category">
    <e-dropdowntree-treeSettings expandOn="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@CategoryHierarchy" text="CategoryName" value="CategoryId" child="SubCategories"></e-dropdowntree-fields>
</ejs-dropdowntree>

场景：以层级结构展示产品分类

html

<ejs-dropdowntree id="categories" placeholder="Select Category">
    <e-dropdowntree-treeSettings expandOn="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@CategoryHierarchy" text="CategoryName" value="CategoryId" child="SubCategories"></e-dropdowntree-fields>
</ejs-dropdowntree>

Pattern 2: Multi-Select with Checkboxes

模式2：带复选框的多选

Scenario: Allow users to select multiple items with automatic parent-child dependency

html

<ejs-dropdowntree id="multiSelect" showCheckBox="true" allowMultiSelection="true" mode="Box">
    <e-dropdowntree-treeSettings autoCheck="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@DataSource" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

场景：允许用户选择多个项，并自动同步父子依赖

html

<ejs-dropdowntree id="multiSelect" showCheckBox="true" allowMultiSelection="true" mode="Box">
    <e-dropdowntree-treeSettings autoCheck="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@DataSource" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

Pattern 3: Lazy Loading Large Datasets

模式3：大型数据集懒加载

Scenario: Load only visible nodes to improve performance with large trees

html

<ejs-dropdowntree id="lazyLoad">
    <e-dropdowntree-treeSettings loadOnDemand="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@RemoteDataManager" text="Name" value="Id" child="Children" hasChildren="HasChild"></e-dropdowntree-fields>
</ejs-dropdowntree>

场景：仅加载可见节点以提升大型树形结构的性能

html

<ejs-dropdowntree id="lazyLoad">
    <e-dropdowntree-treeSettings loadOnDemand="true"></e-dropdowntree-treeSettings>
    <e-dropdowntree-fields dataSource="@RemoteDataManager" text="Name" value="Id" child="Children" hasChildren="HasChild"></e-dropdowntree-fields>
</ejs-dropdowntree>

Pattern 4: Remote Data with Filtering

模式4：带过滤的远程数据

Scenario: Fetch tree data remotely and enable real-time search C# (TreeViewController.cs):

csharp

public ActionResult RemoteData()
{
    DropDownTreeFields parentData = new DropDownTreeFields();
    DropDownTreeFields childData = new DropDownTreeFields();
    object data = new DataManager
    {
        Url = "https://services.odata.org/V4/Northwind/Northwind.svc",
        Adaptor = "ODataV4Adaptor",
        CrossDomain = true
    };
    // Parent data mapping
    parentData.Query = "new ej.data.Query().from('Employees').select('EmployeeID,FirstName,Title').take(5)";
    parentData.Value = "EmployeeID";
    parentData.Text = "FirstName";
    parentData.HasChildren = "EmployeeID";
    parentData.Child = childData;
    parentData.DataSource = data;
    // Child data mapping  
    childData.Query = "new ej.data.Query().from('Orders').select('OrderID,EmployeeID,ShipName').take(5)";
    childData.Value = "OrderID";
    childData.Text = "ShipName";
    childData.ParentValue = "EmployeeID";
    childData.DataSource = data;
    ViewBag.remoteFields = parentData;
    return View();
}

html


<ejs-dropdowntree id="remoteFilter" allowFiltering="true" filterType="StartsWith">
    <e-dropdowntree-fields child="ViewBag.child" query="new ej.data.Query().from('Employees').select('EmployeeID,FirstName,Title').take(5)" value="EmployeeID" text="FirstName" hasChildren="EmployeeID">
        <e-data-manager url="https://services.odata.org/V4/Northwind/Northwind.svc" adaptor="ODataV4Adaptor" crossDomain="true"></e-data-manager>
    </e-dropdowntree-fields>
</ejs-dropdowntree>

场景：远程获取树形数据并启用实时搜索 C# (TreeViewController.cs):

csharp

public ActionResult RemoteData()
{
    DropDownTreeFields parentData = new DropDownTreeFields();
    DropDownTreeFields childData = new DropDownTreeFields();
    object data = new DataManager
    {
        Url = "https://services.odata.org/V4/Northwind/Northwind.svc",
        Adaptor = "ODataV4Adaptor",
        CrossDomain = true
    };
    // Parent data mapping
    parentData.Query = "new ej.data.Query().from('Employees').select('EmployeeID,FirstName,Title').take(5)";
    parentData.Value = "EmployeeID";
    parentData.Text = "FirstName";
    parentData.HasChildren = "EmployeeID";
    parentData.Child = childData;
    parentData.DataSource = data;
    // Child data mapping  
    childData.Query = "new ej.data.Query().from('Orders').select('OrderID,EmployeeID,ShipName').take(5)";
    childData.Value = "OrderID";
    childData.Text = "ShipName";
    childData.ParentValue = "EmployeeID";
    childData.DataSource = data;
    ViewBag.remoteFields = parentData;
    return View();
}

html


<ejs-dropdowntree id="remoteFilter" allowFiltering="true" filterType="StartsWith">
    <e-dropdowntree-fields child="ViewBag.child" query="new ej.data.Query().from('Employees').select('EmployeeID,FirstName,Title').take(5)" value="EmployeeID" text="FirstName" hasChildren="EmployeeID">
        <e-data-manager url="https://services.odata.org/V4/Northwind/Northwind.svc" adaptor="ODataV4Adaptor" crossDomain="true"></e-data-manager>
    </e-dropdowntree-fields>
</ejs-dropdowntree>

Pattern 5: Custom Display Modes

模式5：自定义显示模式

Scenario: Display selected multiple items in chip format

html

<ejs-dropdowntree id="chipMode" showCheckBox="true" allowMultiSelection="true" mode="Box" delimiterChar=",">
    <e-dropdowntree-fields dataSource="@DataSource" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

场景：以芯片格式展示选中的多个项

html

<ejs-dropdowntree id="chipMode" showCheckBox="true" allowMultiSelection="true" mode="Box" delimiterChar=",">
    <e-dropdowntree-fields dataSource="@DataSource" text="Text" value="Id" child="Children"></e-dropdowntree-fields>
</ejs-dropdowntree>

Key Properties Reference

核心属性参考

Property	Type	Default	Purpose
`dataSource`	DataManager \| Array	-	Specifies the data items for the DropDownTree
`fields`	FieldsModel	-	Maps data source fields to DropDownTree properties
`value`	string[]	-	Gets/sets the currently selected value(s)
`text`	string	-	Gets the currently selected item text
`showCheckBox`	boolean	false	Enables checkbox mode for multiple selection
`allowMultiSelection`	boolean	false	Enables multi-selection without checkboxes
`allowFiltering`	boolean	false	Enables filter bar for searching items
`enabled`	boolean	true	Enables/disables the component
`readonly`	boolean	false	Sets read-only state
`mode`	Mode	'Default'	Display mode for selected items (Default, Delimiter, Box, Custom)
`treeSettings`	TreeSettings	-	Configures tree expansion and selection behavior
`itemTemplate`	string \| Function	-	Template for customizing item display
`valueTemplate`	string \| Function	-	Template for customizing selected value display
`headerTemplate`	string \| Function	-	Template for popup header
`footerTemplate`	string \| Function	-	Template for popup footer
`noRecordsTemplate`	string \| Function	-	Template when no items found
`actionFailureTemplate`	string \| Function	-	Template when remote data fails
`customTemplate`	string \| Function	-	Custom template for selected items with mode='Custom'
`placeholder`	string	-	Watermark text for input element
`floatLabelType`	FloatLabelType	'Never'	Label floating behavior
`locale`	string	'en'	Culture for localization
`enableRtl`	boolean	false	Right-to-left rendering
`enablePersistence`	boolean	false	Persist state across sessions
`cssClass`	string	-	CSS class for styling
`filterType`	TreeFilterType	'StartsWith'	Search filter algorithm
`ignoreCase`	boolean	true	Case-insensitive search
`ignoreAccent`	boolean	false	Ignore diacritical marks in search

属性	类型	默认值	用途
`dataSource`	DataManager \| Array	-	指定DropDownTree的数据项
`fields`	FieldsModel	-	将数据源字段映射到DropDownTree属性
`value`	string[]	-	获取/设置当前选中的值(多个)
`text`	string	-	获取当前选中项的文本
`showCheckBox`	boolean	false	启用复选框模式以支持多选
`allowMultiSelection`	boolean	false	启用无复选框的多选
`allowFiltering`	boolean	false	启用过滤栏以搜索项
`enabled`	boolean	true	启用/禁用组件
`readonly`	boolean	false	设置只读状态
`mode`	Mode	'Default'	选中项的显示模式(Default、Delimiter、Box、Custom)
`treeSettings`	TreeSettings	-	配置树形展开与选择行为
`itemTemplate`	string \| Function	-	用于自定义项展示的模板
`valueTemplate`	string \| Function	-	用于自定义选中值显示的模板
`headerTemplate`	string \| Function	-	弹出框页眉的模板
`footerTemplate`	string \| Function	-	弹出框页脚的模板
`noRecordsTemplate`	string \| Function	-	无数据时的模板
`actionFailureTemplate`	string \| Function	-	远程数据加载失败时的模板
`customTemplate`	string \| Function	-	mode='Custom'时选中项的自定义模板
`placeholder`	string	-	输入框的水印文本
`floatLabelType`	FloatLabelType	'Never'	标签浮动行为
`locale`	string	'en'	本地化的文化设置
`enableRtl`	boolean	false	从右到左渲染
`enablePersistence`	boolean	false	跨会话保留状态
`cssClass`	string	-	用于样式的CSS类
`filterType`	TreeFilterType	'StartsWith'	搜索过滤算法
`ignoreCase`	boolean	true	不区分大小写的搜索
`ignoreAccent`	boolean	false	搜索时忽略重音符号

Common Use Cases

常见使用场景

Organizational Hierarchies: Display employee reporting structures, department hierarchies
File System Navigation: Show folder structures with expandable directories
Category Selection: Product categories with subcategories for e-commerce
Geographic Hierarchies: Country-State-City nested selections
Permission/Role Hierarchies: Multi-level permission or role selection
Task Breakdown Structures: Project tasks organized hierarchically
Localization Selection: Language families and specific languages
Feature/Module Selection: Application features organized by module and feature

Next Steps: Choose a reference document above based on your current task. Each reference file contains detailed examples, property explanations, and implementation guidelines specific to that feature area.

组织层级结构：展示员工汇报结构、部门层级
文件系统导航：显示带可展开目录的文件夹结构
分类选择：电商平台中带子分类的产品分类
地理层级结构：国家-州-城市的嵌套选择
权限/角色层级：多级权限或角色选择
任务分解结构：按层级组织的项目任务
本地化选择：语言家族及具体语言选择
功能/模块选择：按模块和功能组织的应用功能

下一步：根据当前任务选择上方的参考文档。每个参考文件都包含针对该功能领域的详细示例、属性说明和实现指南。