syncfusion-react-dropdown-tree

实现 Dropdown Tree

Dropdown Tree 组件会在下拉界面中以可折叠的树形结构显示分层数据。它将树形导航与下拉菜单的无障碍功能相结合，支持通过复选框进行多选、为大型数据集延迟加载、通过模板和事件进行全面自定义、筛选，以及支持 RTL 和本地化的完整无障碍功能。

何时使用此技能

在需要以下功能时，立即使用 Dropdown Tree：

• 显示分层数据 - 展示嵌套类别、组织结构、文件树或部门层级
• 启用多选 - 允许用户通过复选框或键盘修饰键选择多个项目
• 支持延迟加载 - 按需加载子项，提升大型数据集的性能
• 自定义显示 - 使用模板格式化项目、标题、页脚、已选值或错误状态
• 实现筛选 - 启用搜索功能，并配置筛选类型（StartsWith、EndsWith、Contains）
• 确保无障碍功能 - 提供符合 WAI-ARIA 的支持、键盘导航和屏幕阅读器支持
• 支持多种语言 - 使用可自定义的键和 RTL 支持实现 UI 本地化
• 绑定远程数据 - 集成 OData、OData V4、Web API 或其他远程数据服务
• 处理复杂的选择逻辑 - 使用事件、自动检查层级，或有选择地禁用节点

组件概述

Dropdown Tree 的功能包括：

• 分层显示：本地（分层/自引用）和远程数据源，支持灵活绑定
• 多种选择模式：带自动检查的复选框、使用 Ctrl/Shift 键多选、单选（默认）
• 灵活的模板：项目、值、标题、页脚、noRecords 和 actionFailure 模板，支持自定义渲染
• 性能优化：延迟加载（按需加载），高效处理大型数据集
• 搜索与筛选：内置筛选栏，支持配置筛选类型和区分大小写选项
• 全面的事件：change、select、dataBound、filtering、beforeOpen、focus、keyPress 和弹出窗口事件
• 无障碍功能：完整的 WAI-ARIA 支持（角色、属性）、键盘导航、屏幕阅读器支持，符合 WCAG 2.2 标准
• 本地化：支持多种语言，提供 4 个可自定义键和区域设置覆盖
• RTL 支持：从右向左的布局渲染
• 树设置：高级配置（expandOn、autoCheck、loadOnDemand、checkDisabledChildren）
• 字段映射：支持灵活的数据结构（value、text、child、parentValue、expanded、hasChildren、selectable、iconCss、imageUrl、htmlAttributes）
• 显示模式：已选项目支持默认、分隔符和自定义模式

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包依赖项（npm install 命令）
• React/TypeScript 项目设置（Vite 和 Create React App）
• 基本组件实现和初始化
• CSS 导入和主题配置
• 首次渲染和最简可运行示例

数据绑定

📄 阅读： references/data-binding.md

• 本地数据绑定（分层和自引用结构）
• 使用 DataManager 和各种适配器（OData、OData V4、WebAPI、URL）绑定远程数据
• value、text、child、parentValue、expanded、hasChildren 的字段映射
• 大型数据集的按需加载（延迟加载）
• 使用 selectable 字段阻止节点选择
• 远程数据服务的查询配置

复选框与多选

📄 阅读： references/checkbox-selection.md

• 使用 showCheckBox 属性启用复选框支持
• 多选工作流和访问所选值
• 自动勾选层级行为（父子同步）
• 全选功能，可使用 selectAllText 和 unSelectAllText 自定义文本
• 部分选中时显示中间复选框状态
• CheckDisabledChildren 行为，用于处理禁用节点

模板

📄 阅读： references/templates.md

• 项模板，用于自定义列表项渲染
• 值模板，用于自定义所选内容的显示
• 页眉模板，用于在项目上方显示静态内容
• 页脚模板，用于在项目下方显示静态内容
• NoRecords 模板，用于处理空状态
• ActionFailure 模板，用于处理错误状态
• CustomTemplate，用于自定义多选显示
• 模板表达式语法和数据访问模式

多选与筛选

📄 阅读： references/multi-selection-filtering.md

• allowMultiSelection 属性以及 Ctrl/Shift 键盘交互
• 显示模式：Default、Delimiter、Custom
• delimiterChar 和 mode 配置
• allowFiltering 和筛选栏实现
• 筛选类型：StartsWith、EndsWith、Contains
• filterBarPlaceholder 自定义
• ignoreCase 和 ignoreAccent 选项

树设置与配置

📄 阅读： references/tree-settings.md

• 使用 loadOnDemand 实现延迟加载
• 使用 autoCheck 实现层级复选框同步
• expandOn 行为（Auto、Click、DblClick、None）
• 使用 checkDisabledChildren 处理禁用节点
• 树的展开和折叠控制

字段映射与自定义数据结构

📄 阅读： references/field-mapping.md

• 核心字段：value、text、dataSource、child、parentValue
• 节点状态字段：expanded、hasChildren、selected、selectable
• 显示增强字段：iconCss、imageUrl、htmlAttributes
• 用于远程数据的 Query 和 tableName
• 层级数据的嵌套字段映射

高级功能与 API 参考

📄 阅读： references/advanced-features.md

• 属性（60 多个属性及其说明和示例）
• 方法（getSelectedNodes、getCheckedNodes、setCheckedNodes 等）
• 事件（change、select、dataBound、filtering、beforeOpen、focus、keyPress、popup）
• 事件参数（EventArgs 结构及属性说明）
• 样式和 CSS 自定义
• 性能优化技巧

无障碍与本地化

📄 阅读： references/accessibility-localization.md

• 符合 WCAG 2.2 和 Section 508 合规标准
• WAI-ARIA 属性和角色（listbox、treeitem、checkbox、group 等）
• 键盘导航快捷键（Alt+Down、方向键、Enter、Space 等）
• 屏幕阅读器和辅助技术支持
• 本地化键（noRecordsTemplate、actionFailureTemplate、overflowCountTemplate、totalCountTemplate）
• 使用 locale 属性自定义区域设置
• 使用 enableRtl 支持 RTL（从右到左）语言

快速开始

使用层级数据的基本下拉树

import { DropDownTreeComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-dropdowns/styles/material.css';

function App() {
  const data = [
    { id: '1', name: 'Electronics', expanded: true },
    { id: '2', name: 'Laptops', parentId: '1' },
    { id: '3', name: 'Phones', parentId: '1' },
    { id: '4', name: 'Appliances' },
  ];

  return (
    <DropDownTreeComponent
      id="dropdowntree"
      fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId', hasChildren: 'hasChild' }}
      placeholder="Select an item"
    />
  );
}

export default App;

使用复选框和自动勾选

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId', hasChildren: 'hasChild' }}
  showCheckBox={true}
  showSelectAll={true}
  treeSettings={{ autoCheck: true }}
  placeholder="Select items"
/>

使用筛选

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId' }}
  allowFiltering={true}
  filterType="Contains"
  filterBarPlaceholder="Search items..."
  placeholder="Select an item"
/>

使用自定义模板

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: data, value: 'id', text: 'name', parentValue: 'parentId' }}
  itemTemplate={(props) => (
    <div style={{ display: 'flex', gap: '8px', alignItems: 'center' }}>
      <span>{props.name}</span>
      <small style={{ color: '#999' }}>({props.category})</small>
    </div>
  )}
  valueTemplate={(props) => <span>{props.name}</span>}
  placeholder="Select item"
/>

常见模式

模式 1：自引用数据绑定

适用于包含父级引用的扁平数据结构：

const data = [
  { id: 1, name: 'Discover Music', hasChild: true, expanded: true },
  { id: 2, pid: 1, name: 'Hot Singles' },
  { id: 3, pid: 1, name: 'Rising Artists' },
  { id: 7, name: 'Sales and Events', hasChild: true },
  { id: 8, pid: 7, name: '100 Albums' },
];

<DropDownTreeComponent
  id="dropdowntree"
  fields={{
    dataSource: data,
    value: 'id',
    text: 'name',
    parentValue: 'pid',
    hasChildren: 'hasChild',
  }}
/>

模式 2：处理选择变更事件

const handleChange = (args) => {
  console.log('Old values:', args.oldValue); // string[]
  console.log('New values:', args.value); // string[]
  console.log('User interaction:', args.isInteracted); // boolean
};

const handleSelect = (args) => {
  console.log('Action:', args.action); // 'select' or 'unselect'
  console.log('Item data:', args.itemData); // object
};

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  onChange={handleChange}
  onSelect={handleSelect}
/>

模式 3：使用自动勾选的多选

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  showCheckBox={true}
  treeSettings={{ autoCheck: true }}
  mode="Default"
  delimiterChar=", "
  placeholder="Select multiple items"
/>

模式 4：对大型数据集进行延迟加载

const remoteData = new DataManager({
  url: 'url',
  adaptor: new UrlAdaptor(),
});

<DropDownTreeComponent
  id="dropdowntree"
  fields={{ dataSource: remoteData, value: 'id', text: 'name', hasChildren: 'hasChild' }}
  treeSettings={{ loadOnDemand: true }}
  placeholder="Loading..."
/>

模式 5：使用 IconCss 自定义项目样式

const data = [
  { id: 1, name: 'Documents', iconCss: 'e-folder', hasChild: true },
  { id: 2, pid: 1, name: 'Resume.pdf', iconCss: 'e-pdf' },
  { id: 3, pid: 1, name: 'Report.docx', iconCss: 'e-docx' },
];

<DropDownTreeComponent
  id="dropdowntree"
  fields={{
    dataSource: data,
    value: 'id',
    text: 'name',
    iconCss: 'iconCss',
    parentValue: 'pid',
    hasChildren: 'hasChild',
  }}
/>

模式 6：RTL 与本地化支持

<DropDownTreeComponent
  id="dropdowntree"
  fields={fields}
  enableRtl={true}
  locale="ar"
  placeholder="اختر عنصرا"
/>

主要属性概览

属性	类型	描述
核心
id	string	组件的唯一标识符
fields	FieldsModel	数据源和字段映射配置
placeholder	string	输入占位文本
enabled	boolean	启用/禁用组件（默认值：true）
选择
showCheckBox	boolean	启用复选框多选（默认值：false）
showSelectAll	boolean	显示“全选”复选框（默认值：false）
selectAllText	string	“全选”标签文本
unSelectAllText	string	“取消全选”标签文本
allowMultiSelection	boolean	启用使用 Ctrl/Shift 键进行多选
模板
itemTemplate	string | Function	自定义项渲染
valueTemplate	string | Function	自定义所选值显示
headerTemplate	string | Function	自定义页眉内容
footerTemplate	string | Function	自定义页脚内容
noRecordsTemplate	string | Function	空状态模板
actionFailureTemplate	string | Function	错误状态模板
筛选
allowFiltering	boolean	启用搜索/筛选栏（默认值：false）
filterType	TreeFilterType	筛选类型：StartsWith、EndsWith、Contains
filterBarPlaceholder	string	筛选栏占位文本
ignoreCase	boolean	筛选时忽略大小写（默认值：true）
ignoreAccent	boolean	筛选时忽略变音符号
树设置
treeSettings	TreeSettingsModel	树行为配置（autoCheck、loadOnDemand、expandOn）
显示
mode	string	显示模式：Default、Delimiter、Custom
delimiterChar	string	多选分隔符（默认值：", "）
customTemplate	string	自定义多选显示模板
本地化与 RTL
locale	string	区域性代码（默认值："en"）
enableRtl	boolean	启用从右到左布局
enablePersistence	boolean	在页面重新加载时保留状态
样式
cssClass	string	根元素和弹出窗口的 CSS 类
width	string | number	组件宽度
popupHeight	string | number	弹出窗口高度
htmlAttributes	object	组件的 HTML 属性

选择指南

选择数据绑定方式：

• 本地层级数据 - 使用带有 child 属性的嵌套 JSON 对象，适用于中小型数据集
• 本地自引用数据 - 使用带有 parentValue 字段的扁平数组，适用于结构化数据
• 使用 DataManager 的远程数据 - 使用 OData/Web API，适用于大型数据集、动态加载和实时数据

选择模式：

• 单选 - 默认模式（无复选框、无多选），只读视觉选择
• 复选框 - 使用 showCheckBox={true} 进行显式多选
• 多选 - 使用 allowMultiSelection={true} 通过 Ctrl/Shift 键盘选择
• 自动勾选 - 将复选框与 treeSettings={{ autoCheck: true }} 结合使用，以同步层级状态

选择模板：

• itemTemplate - 自定义每个树项的格式（名称 + 描述、图标、徽章）
• valueTemplate - 自定义输入框中的显示内容（组合文本、格式化值）
• headerTemplate - 列表上方的静态控件（说明、搜索帮助、自定义控件）
• footerTemplate - 列表下方的静态内容（数量摘要、操作按钮）
• noRecordsTemplate - 没有数据或搜索无结果时显示的空状态
• actionFailureTemplate - 数据获取失败时显示的错误消息

何时使用延迟加载：

• 大型数据集（1000+ 项）
• 对性能要求高的应用
• 通过分页从远程 API 获取数据
• 层级较多的结构

何时使用筛选：

• 需要搜索的大型数据集
• 方便用户查找项目
• 降低选择时的认知负担

Next Steps

• Get started → Read getting-started.md
• Bind data → Read data-binding.md
• Add checkboxes → Read checkbox-selection.md
• Enable filtering → Read multi-selection-filtering.md
• Configure trees → Read tree-settings.md
• Map fields → Read field-mapping.md
• Customize → Read templates.md
• Access APIs → Read advanced-features.md
• Enhance UX → Read accessibility-localization.md