syncfusion-javascript-dropdowntree

实现 Syncfusion Dropdown Tree

---

何时使用此技能

在以下情况下使用 Dropdown Tree 控件：

• 以紧凑的下拉格式显示层级数据，并采用类似树状的结构
• 支持从树节点中多选，并提供复选框
• 按需加载大型数据集（延迟加载），以优化性能
• 自定义树的外观，包括项目模板、页眉和页脚
• 处理父子依赖关系，并自动传播复选框状态
• 借助本地化功能支持多种语言
• 提供键盘导航，并为使用辅助技术的用户提供无障碍支持

Dropdown Tree 非常适用于组织架构、类别选择、位置／区域选择器以及权限／角色管理界面等场景。

---

组件概述

Syncfusion Dropdown Tree 控件支持从以树状结构显示的层级数据中选择单个或多个值。主要功能包括：

• 数据绑定：本地（层级式／自引用式）和远程（OData、Web API、DataManager）
• 复选框：支持多选，并可选择是否启用父子项自动勾选
• 全选：页眉中内置复选框，可选择／取消选择所有项目
• 模板：自定义项目、值、页眉、页脚和无记录内容
• 延迟加载：按需加载子数据，减少初始带宽占用
• 排序：按升序／降序显示项目
• 筛选：动态搜索和筛选树节点
• 本地化：支持多语言和文本自定义
• 无障碍支持：支持键盘导航和屏幕阅读器
• 多选模式：提供 Box、Delimiter、Default 或 Custom 显示模式

---

文档导航

入门

📄 阅读： references/getting-started.md

• 安装和软件包依赖项
• 开发环境设置
• CSS 导入和主题配置
• 基本 HTML 初始化
• 使用 TypeScript 和 ES5 示例创建首个 Dropdown Tree

数据绑定和树结构

📄 阅读： references/data-binding.md

• 使用层级结构进行本地数据绑定
• 自引用数据绑定模式
• 远程数据绑定（OData、Web API、DataManager）
• 配置按需加载（延迟加载）
• 字段映射和数据结构要求
• 不同数据源的实用示例

复选框功能和选择

📄 阅读： references/checkbox-features.md

• 使用 showCheckBox 属性启用复选框
• 选择单个项目
• 父子项自动勾选传播
• 在弹出窗口页眉中使用全选功能
• 自定义全选文本和行为
• 以编程方式管理所选项目

模板和自定义

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

• 用于自定义列表渲染的项目模板
• 用于显示所选值的值模板
• 用于自定义弹出窗口页眉的页眉模板
• 用于设置弹出窗口页脚内容的页脚模板
• 用于处理空状态的无记录模板
• 用于错误场景的操作失败模板
• 模板表达式语法和最佳实践

本地化和无障碍支持

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

• 本地化库的设置和用法
• 多语言文本自定义
• 默认和自定义区域设置
• 键盘导航支持
• 屏幕阅读器兼容性
• WCAG 无障碍功能

---

快速入门示例

基本设置（TypeScript）

import { DropDownTree } from '@syncfusion/ej2-dropdowns';

// Define hierarchical data
let continents = [
    {
        code: 'AF', 
        name: 'Africa', 
        countries: [
            { code: 'NGA', name: 'Nigeria' },
            { code: 'EGY', name: 'Egypt' }
        ]
    },
    {
        code: 'AS', 
        name: 'Asia',
        expanded: true,
        countries: [
            { code: 'IND', name: 'India', selected: true },
            { code: 'JPN', name: 'Japan' }
        ]
    }
];

// Initialize Dropdown Tree
let ddtree = new DropDownTree({
    fields: { 
        dataSource: continents, 
        value: 'code', 
        text: 'name', 
        child: 'countries' 
    }
});

ddtree.appendTo('#ddtElement');

HTML 元素

<input type="text" id="ddtElement" />

---

核心概念

1. 层级数据结构

层级数据使用嵌套数组表示父子关系：

let hierarchicalData = [
    {
        id: 1,
        name: 'Parent Item',
        children: [
            { id: 2, name: 'Child 1' },
            { id: 3, name: 'Child 2' }
        ]
    }
];

2. 自引用数据结构

自引用数据通过父 ID 引用来表示关系：

let selfRefData = [
    { id: 1, name: 'Parent', parentId: null },
    { id: 2, name: 'Child 1', parentId: 1 },
    { id: 3, name: 'Child 2', parentId: 1 }
];

3. 单选与多选

• 单选：用户可以选择一个项（默认行为）
• 多选：使用 allowMultiSelection: true 或 showCheckBox: true 启用

4. 父子复选框依赖关系

当 treeSettings 中设置 autoCheck: true 时：

• 选中父项会自动选中所有子项
• 取消选中父项会自动取消选中所有子项
• 仅选中部分子项时，会出现混合状态（中间状态）

---

FieldsModel 配置

fields 属性使用 FieldsModel 将数据源字段映射到 Dropdown Tree 属性。

FieldsModel 属性

属性	类型	描述	示例
dataSource	DataManager | Object[]	数据数组或 DataManager 实例	[{...}, {...}]
value	string	项值/ID 对应的字段名	'id' 或 'code'
text	string	显示文本对应的字段名	'name' 或 'title'
child	string | FieldsModel	子项集合对应的字段名（层级结构）	'children' 或 'items'
parentValue	string	父项引用对应的字段名（自引用）	'parentId' 或 'pid'
hasChildren	string	指示项是否有子项的字段名	'hasChild' 或 'hasItems'
expanded	string	展开状态对应的字段名	'expanded' 或 'isExpanded'
selected	string	选中状态对应的字段名	'selected' 或 'isSelected'
iconCss	string	图标 CSS 类对应的字段名	'iconClass'
imageUrl	string	图像 URL 对应的字段名	'imageUrl' 或 'icon'
htmlAttributes	string	HTML 属性对应的字段名	'htmlAttrs'
tooltip	string	工具提示文本对应的字段名	'title' 或 'tooltip'
selectable	string	项是否可选对应的字段名	'canSelect'
query	Query	DataManager 的外部查询	自定义 Query 对象
tableName	string	服务端数据的表名	'EmployeeTable'

FieldsModel 示例

使用自定义字段的层级数据

let ddtree = new DropDownTree({
    fields: {
        dataSource: hierarchicalData,
        value: 'id',
        text: 'name',
        child: 'subitems',
        expanded: 'isExpanded',
        iconCss: 'iconClass'
    }
});
ddtree.appendTo('#ddtElement');

自引用数据

let ddtree = new DropDownTree({
    fields: {
        dataSource: selfRefData,
        value: 'id',
        text: 'name',
        parentValue: 'parentId',
        hasChildren: 'hasChild'
    }
});
ddtree.appendTo('#ddtElement');

使用 OData 的远程数据

import { DataManager, ODataV4Adaptor } from '@syncfusion/ej2-data';

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Employees',
            adaptor: new ODataV4Adaptor()
        }),
        value: 'EmployeeID',
        text: 'FirstName',
        hasChildren: 'EmployeeID'
    }
});
ddtree.appendTo('#ddtElement');

---

TreeSettingsModel 配置

treeSettings 属性使用 TreeSettingsModel 配置树相关行为。

TreeSettingsModel 属性

属性	类型	描述	默认值
loadOnDemand	boolean	启用子项的延迟加载	false
autoCheck	boolean	启用父子复选框依赖关系	false
checkDisabledChildren	boolean	父项选中时包含已禁用的子项	false
expandOn	ExpandOn	展开/折叠操作的触发方式	ExpandOn.Auto

ExpandOn 枚举值

值	描述
Auto	桌面端双击，移动端单击
Click	桌面端和移动端均为单击
DblClick	桌面端和移动端均为双击
None	禁用展开/折叠

TreeSettingsModel 示例

延迟加载配置

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    treeSettings: {
        loadOnDemand: true  // Children load when parent expands
    }
});
ddtree.appendTo('#ddtElement');

支持已禁用子项的自动选中

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    treeSettings: {
        autoCheck: true,
        checkDisabledChildren: true  // Disabled items get checked too
    }
});
ddtree.appendTo('#ddtElement');

自定义展开触发方式

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    treeSettings: {
        expandOn: 'Click'  // Single-click to expand/collapse
    }
});
ddtree.appendTo('#ddtElement');

---

📋 API 属性参考

📄 完整的 API 属性文档，包含示例和类型规范

🔗 打开 api-properties.md

内容包括：

• ✅ 55+ 个属性 - 记录每个属性的类型、默认值和描述
• ✅ 10 个类别 - 基本、选择、模板、弹出窗口、筛选、排序、样式、状态、HTML 安全、本地化
• ✅ 100+ 个示例 - 每个属性的实际代码示例
• ✅ 类型规范 - 完整的类型信息和默认值
• ✅ 最佳实践 - 使用模式和建议

---

🔧 API 方法参考

📄 完整的 API 方法文档，包含参数详情和示例

🔗 打开 api-methods.md

内容包括：

• ✅ 16 个方法 - 完整记录所有组件方法
• ✅ 6 个类别 - 生命周期、数据与值、弹出窗口、DOM、事件管理、模块注入
• ✅ 参数规格 - 完整的参数类型、说明和返回类型
• ✅ 可运行示例 - 每个方法均提供可用于生产环境的代码
• ✅ 使用场景 - 说明各方法的使用时机和方式

---

🎯 API 事件参考

📄 完整的 API 事件文档，包含事件参数属性和示例

🔗 打开 api-events.md

内容包括：

• ✅ 13 个事件 - 完整记录所有组件事件
• ✅ 7 个类别 - 选择、数据、筛选、弹出窗口、焦点、键盘、生命周期
• ✅ 8 种事件参数类型 - 完整的属性映射（30 多个属性）
• ✅ 事件详情 - 说明每个事件的触发时机及其提供的数据
• ✅ 实际示例 - 实用的事件处理实现

---

常见模式

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

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    showSelectAll: true,
    treeSettings: { autoCheck: true },
    change: (args) => {
        console.log('Selected items:', args.value);
    }
});
ddtree.appendTo('#ddtElement');

适用场景：用户需要选择多个具有父子依赖关系的项目。

模式 2：按需加载大型数据集

let ddtree = new DropDownTree({
    fields: { 
        dataSource: dataManager, 
        value: 'id', 
        text: 'name',
        parentValue: 'parentId'
    },
    treeSettings: { loadOnDemand: true }
});
ddtree.appendTo('#ddtElement');

适用场景：处理大型层级结构（1000 个以上项目）。

模式 3：使用模板自定义项目显示

let ddtree = new DropDownTree({
    fields: { dataSource: data, text: 'name', value: 'id' },
    itemTemplate: '<div class="item-row"><span>${name}</span> <small>${department}</small></div>',
    valueTemplate: '<span class="selected-badge">${name}</span>'
});
ddtree.appendTo('#ddtElement');

适用场景：需要显示其他数据字段。

模式 4：使用筛选功能处理远程数据

import { DataManager, ODataV4Adaptor } from '@syncfusion/ej2-data';

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'https://api.example.com/items',
            adaptor: new ODataV4Adaptor()
        }),
        value: 'id',
        text: 'name'
    },
    allowFiltering: true,
    filterBarPlaceholder: 'Search items...',
    filterType: 'Contains'
});
ddtree.appendTo('#ddtElement');

适用场景：从远程服务获取数据并支持搜索。

模式 5：使用分隔符模式自定义“全选”

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', parentValue: 'pid' },
    showCheckBox: true,
    showSelectAll: true,
    selectAllText: 'Select All Items',
    unSelectAllText: 'Clear All',
    mode: 'Delimiter',
    delimiterChar: '; ',
    allowMultiSelection: true
});
ddtree.appendTo('#ddtElement');

适用场景：希望显示直观的复选框文本和分隔显示内容。

模式 6：动态更新数据

let ddtree = new DropDownTree({
    fields: { dataSource: [], value: 'id', text: 'name', child: 'items' }
});
ddtree.appendTo('#ddtElement');

// Later, update data
let newData = [{ id: 1, name: 'Item 1', items: [] }];
ddtree.fields.dataSource = newData;
ddtree.refresh();  // Re-render

适用场景：初始化后数据会动态变化。

模式 7：通过验证以编程方式设置值

let ddtree = new DropDownTree({
    fields: { dataSource: data, value: 'id', text: 'name', child: 'items' },
    showCheckBox: true,
    change: (args) => {
        if (args.value.length > 5) {
            console.warn('Maximum 5 items can be selected');
            // Reset to previous value
            ddtree.value = args.oldValue;
        }
    }
});
ddtree.appendTo('#ddtElement');

适用场景：需要强制执行选择限制。

---

使用场景与实现指南

组织层级导航

场景：部门/员工选择，支持多选和角色分配

let employees = [
    { id: 1, name: 'IT Department', hasChild: true },
    { id: 2, pid: 1, name: 'John Doe', department: 'IT' },
    { id: 3, pid: 1, name: 'Jane Smith', department: 'IT' },
    { id: 4, name: 'HR Department', hasChild: true },
    { id: 5, pid: 4, name: 'Mike Johnson', department: 'HR' }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: employees, 
        value: 'id', 
        text: 'name', 
        parentValue: 'pid',
        hasChildren: 'hasChild'
    },
    showCheckBox: true,
    treeSettings: { autoCheck: true },
    itemTemplate: '<div>${name} <span class="text-muted">${department}</span></div>',
    change: (args) => {
        assignRolesToSelectedEmployees(args.value);
    }
});
ddtree.appendTo('#employeeSelection');

地理位置/区域选择

场景：选择国家 → 州 → 城市，并采用延迟加载

import { DataManager, WebApiAdaptor } from '@syncfusion/ej2-data';

let ddtree = new DropDownTree({
    fields: {
        dataSource: new DataManager({
            url: 'api/locations',
            adaptor: new WebApiAdaptor()
        }),
        value: 'id',
        text: 'name',
        parentValue: 'parentId',
        hasChildren: 'hasChildren'
    },
    treeSettings: { 
        loadOnDemand: true  // Load children on demand
    },
    allowFiltering: true,
    filterBarPlaceholder: 'Search locations...',
    change: (args) => {
        updateMapWithSelectedLocation(args.value);
    }
});
ddtree.appendTo('#locationPicker');

基于类别的产品筛选

场景：显示产品类别、项目数量和图标

let categories = [
    { 
        id: 'cat1', 
        name: 'Electronics', 
        count: 125,
        icon: 'e-icons e-mobile',
        products: [
            { id: 'prod1', name: 'Mobile Phones', count: 45, icon: 'e-icons e-phone' },
            { id: 'prod2', name: 'Laptops', count: 30, icon: 'e-icons e-laptop' }
        ]
    }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: categories, 
        value: 'id', 
        text: 'name', 
        child: 'products',
        iconCss: 'icon'
    },
    itemTemplate: `
        <div class="category-item">
            <i class="\${icon}"></i>
            <span>\${name}</span>
            <span class="badge">\${count}</span>
        </div>
    `,
    change: (args) => {
        filterProductsByCategories(args.value);
    }
});
ddtree.appendTo('#categorySelector');

权限/角色管理

场景：支持选择性启用的多层权限层级结构

let permissions = [
    { id: 'admin', name: 'Admin', hasChild: true },
    { id: 'admin-users', pid: 'admin', name: 'Manage Users' },
    { id: 'admin-system', pid: 'admin', name: 'System Settings' },
    { id: 'user', name: 'User', hasChild: true, disabled: true },
    { id: 'user-profile', pid: 'user', name: 'Edit Profile' }
];

let ddtree = new DropDownTree({
    fields: { 
        dataSource: permissions, 
        value: 'id', 
        text: 'name', 
        parentValue: 'pid',
        hasChildren: 'hasChild'
    },
    showCheckBox: true,
    showSelectAll: true,
    selectAllText: 'Grant All Permissions',
    unSelectAllText: 'Revoke All Permissions',
    treeSettings: { autoCheck: true },
    change: (args) => {
        savePermissionsToRole(args.value);
    }
});
ddtree.appendTo('#permissionSelector');

---

后续步骤

1. 从 references/getting-started.md 开始，安装依赖项并创建第一个控件
2. 选择数据源，并按照 references/data-binding.md 中相应的模式操作
3. 如果需要多选，启用复选框（references/checkbox-features.md）
4. 根据需要使用模板自定义外观（references/templates-and-customization.md）
5. 在实现过程中按需参考此 API 文档

如需针对特定功能或高级场景获取实现方面的帮助，请参考上述相应指南。