syncfusion-aspnetcore-dropdown-tree

实现 Syncfusion DropDownTree 组件

Syncfusion DropDownTree 控件是一种下拉组件，可显示分层树形数据结构，让用户从树形层级中选择单个或多个值。它结合了传统下拉列表的功能与树形结构的层级组织方式，非常适合需要从有序的嵌套数据中进行选择的应用程序。

何时使用此技能

在以下情况下使用此技能：

• 以下拉格式显示分层数据，其中各项具有父子关系
• 支持基于树的选择，并提供节点展开／折叠功能
• 支持多选，并提供复选框或键盘导航
• 实现自定义模板，用于显示项目、页眉、页脚和已选值
• 绑定数据，数据来源可以是本地 JavaScript 数组、远程服务（OData、Web API）或按需延迟加载
• 确保无障碍访问，支持键盘操作（箭头键、Enter、Space）和 ARIA 属性
• 本地化组件，以适配不同的区域和语言
• 禁止选择节点，同时允许选择子节点

主要功能概览

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

• 数据绑定选项：分层数据、自引用数据结构、使用 DataManager 适配器的远程数据服务
• 选择模式：单选、带复选框的多选、以分隔符分隔的显示、芯片／方框模式或自定义模板
• 键盘导航：全面支持键盘操作，包括箭头键、Enter、Space、Home、End、Alt+Up/Down、Escape
• 自定义模板：项目模板、值模板、页眉模板、页脚模板、无记录模板、操作失败模板
• 树配置：展开行为（单击、双击、自动）、按需加载（延迟加载）、自动勾选父子依赖项
• 无障碍访问：符合 WAI-ARIA 标准，支持 listbox 角色、treeitem 角色、ARIA 属性和屏幕阅读器
• 筛选：实时搜索，并可配置筛选类型（StartsWith、EndsWith、Contains）、区分大小写和重音符号处理
• 持久化：在不同浏览器会话之间保留状态
• RTL 支持：为阿拉伯语、希伯来语和其他 RTL 语言提供从右到左的渲染

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 平台设置和先决条件
• NuGet 包安装
• 脚本和样式表引用
• Tag Helper 配置
• DropDownTree 基本初始化
• 首个数据绑定渲染示例
• 使用高级功能前所需的基础知识

数据绑定与层级结构

📄 阅读： references/data-binding.md

• 使用嵌套数组结构绑定分层数据源
• 使用父值关系的自引用数据结构
• 使用 DataManager 和适配器绑定远程数据（OData、ODataV4、WebAPI、URL）
• 大型数据集的按需加载（延迟加载）
• 字段映射配置（text、value、child、parentValue、hasChildren）
• 支持使用 Query 筛选远程数据
• 使用 selectable 属性禁止选择节点

选择与复选框功能

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

• 使用 showCheckBox 属性启用复选框模式
• 使用 allowMultiSelection 属性启用多选
• 自动勾选依赖项，实现父子同步
• 在弹出窗口页眉中提供全选功能
• 已选项目的显示模式（Default、Delimiter、Box、Custom）
• 用于显示已选项目的自定义模板
• 管理勾选状态，并禁止选择已禁用的子项
• 控制展开行为和树交互模式

模板与自定义

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

• 用于自定义列表项外观的项模板
• 用于自定义所选值显示效果的值模板
• 用于自定义弹出窗口标题的标题模板
• 用于自定义弹出窗口页脚的页脚模板
• 用于空搜索结果的无记录模板
• 用于远程数据错误的操作失败模板
• 用于自定义多选显示方式的模板模式（Default、Delimiter、Box、Custom）
• CSS 类自定义和 HTML 属性映射
• 样式与视觉自定义技巧

属性与配置

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

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

事件与交互

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

• 更改事件和值跟踪
• 选择事件（选择／取消选择操作）
• 用于阻止或自定义弹出窗口显示的打开前／弹出窗口事件
• 用于远程数据加载完成的 Data bound 事件
• 用于自定义筛选实现的筛选事件
• 键盘交互事件处理
• 用于状态管理的焦点和失焦事件
• 处理程序中可用的事件参数和属性

无障碍访问与全球化

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

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

快速入门示例

基本初始化

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

启用复选框支持

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

使用模板

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

常见模式

模式 1：分层组织类别

场景：以分层结构显示产品类别

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

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

场景：允许用户选择多个项，并自动处理父子依赖关系

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

模式 3：延迟加载大型数据集

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

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

模式 4：使用筛选的远程数据

场景：从远程获取树数据并启用实时搜索 C#（TreeViewController.cs）：

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

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

模式 5：自定义显示模式

场景：以标签形式显示多个所选项

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

关键属性参考

属性	类型	默认值	用途
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	搜索时忽略变音符号

常见用例

1. 组织层级结构：显示员工汇报关系、部门层级结构
2. 文件系统导航：显示包含可展开目录的文件夹结构
3. 类别选择：用于电商的产品类别及子类别
4. 地理层级结构：国家、省、市的嵌套选择
5. 权限/角色层级结构：多级权限或角色选择
6. 任务分解结构：按层级组织项目任务
7. 本地化选择：语言族及具体语言
8. 功能/模块选择：按模块和功能组织应用功能

---

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