syncfusion-angular-dropdowntree

实现 Syncfusion Angular Dropdown Tree

Dropdown Tree 组件可让你从树形结构的层级数据中选择单个或多个值。它提供数据绑定、复选框、模板和无障碍访问等核心功能，非常适合展示分类选择、组织层级和嵌套数据结构。

何时使用此技能

在以下场景中使用 Dropdown Tree 组件：

• 层级选择 - 允许用户从嵌套的树形数据中选择内容（类别、文件层级、组织树）
• 多选 - 启用基于复选框的多项选择，并可选择自动勾选（同步父子项）
• 动态数据 - 绑定本地数组、自引用结构或远程 OData/REST 端点
• 自定义显示 - 使用项目模板、值模板、页眉和页脚，实现丰富的 UI 自定义
• 大型数据集 - 支持通过延迟加载处理远程数据，以优化性能
• 本地化 - 为不同的语言和文化调整组件文本和消息

组件概览

Dropdown Tree 提供紧凑的下拉输入框，展开后会显示完整的树形结构，并支持强大的筛选、选择和模板功能。与扁平下拉列表不同，它会保留层级关系，便于用户直观地浏览多层级数据。

主要特性：

• 支持选择单个或多个项目
• 基于复选框的多选，并可选择自动勾选
• 支持本地层级数据和自引用数据绑定
• 使用 DataManager 进行远程数据绑定（OData、ODataV4、WebAPI）
• 丰富的模板：项目、值、页眉、页脚、无记录、操作失败
• 内置无障碍访问支持，包括键盘导航和 ARIA 属性
• 全面的本地化支持

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 依赖项和软件包配置
• Angular CLI 配置
• 模块注册 (@syncfusion/ej2-angular-dropdowns)
• CSS 导入和主题配置
• 基本组件集成
• 使用本地数据的首个可运行示例

数据绑定

📄 阅读： references/data-binding.md

• 层级数据结构（嵌套数组）
• 自引用数据绑定（包含 parentValue 的扁平数组）
• 使用 DataManager 绑定远程数据
• OData 和 ODataV4 适配器
• WebAPI 适配器配置
• 基于查询的筛选

复选框功能

📄 阅读： references/checkbox-features.md

• 使用 showCheckBox 属性启用复选框
• 在不影响 UI 的情况下进行多选
• 自动勾选层级行为（同步父子项）
• 全选功能（使用自定义标签的 showSelectAll）
• 复选框状态同步
• 中间状态（部分勾选）

模板与自定义

📄 阅读： references/templates.md

• 用于自定义树项目渲染的项目模板
• 用于显示所选项目的值模板
• 页眉和页脚模板
• 无记录和操作失败模板
• 用于多选的自定义显示模板（Custom 模式）
• 模板表达式和插值

本地化

📄 阅读： references/localization.md

• 支持的本地化键和默认消息
• 设置 locale 和 culture
• 自定义特定区域设置的字符串
• 关键消息：noRecordsTemplate、actionFailureTemplate、overflowCountTemplate、totalCountTemplate
• 多语言配置

API 参考

📄 阅读： references/api-reference.md

• 核心属性和字段映射
• TreeSettings 配置选项
• 常见事件和回调
• 属性配置最佳实践
• 性能优化技巧

方法和事件

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

• 组件方法：showPopup()、hidePopup()、refresh()、clearSelection()、expandAll()、collapseAll()
• 选择事件：change、select
• 弹出窗口事件：open、close、beforeOpen
• 数据事件：dataBound、actionFailure、filtering
• 生命周期事件：created、destroyed
• 用户交互事件：focus、blur、keyPress
• 事件参数和签名
• 完整的可运行示例

快速入门示例

以下是一个使用层级数据的最小可运行示例：

import { Component } from '@angular/core';
import { DropDownTreeModule } from '@syncfusion/ej2-angular-dropdowns';
import { FormsModule, ReactiveFormsModule } from '@angular/forms';

@Component({
  selector: 'app-dropdown-tree',
  template: `<ejs-dropdowntree id='dropdowntree' 
                [fields]='fields' 
                placeholder='Select a category'></ejs-dropdowntree>`,
  standalone: true,
  imports: [DropDownTreeModule, FormsModule, ReactiveFormsModule]
})
export class AppComponent {
  // Hierarchical data structure with nested arrays
  public data = [
    {
      nodeId: '01', nodeText: 'Music',
      nodeChild: [
        { nodeId: '01-01', nodeText: 'Gouttes.mp3' }
      ]
    },
    {
      nodeId: '02', nodeText: 'Videos', expanded: true,
      nodeChild: [
        { nodeId: '02-01', nodeText: 'Naturals.mp4' },
        { nodeId: '02-02', nodeText: 'Wild.mpeg' }
      ]
    }
  ];

  // Field mapping: value=nodeId, text=nodeText, child=nodeChild
  public fields = { 
    dataSource: this.data, 
    value: 'nodeId', 
    text: 'nodeText', 
    child: 'nodeChild' 
  };
}

常见模式

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

@Component({
  template: `<ejs-dropdowntree id='dropdowntree' 
                [fields]='fields' 
                [showCheckBox]='true' 
                [showSelectAll]='true'
                selectAllText='Check All' 
                unSelectAllText='Uncheck All'></ejs-dropdowntree>`,
  standalone: true,
  imports: [DropDownTreeModule, FormsModule, ReactiveFormsModule]
})
export class CheckboxExample {
  public data = [
    { id: 1, name: 'Music', hasChild: true, expanded: true },
    { id: 2, pid: 1, name: 'Hot Singles' },
    { id: 3, pid: 1, name: 'Rising Artists' }
  ];
  public fields = { 
    dataSource: this.data, 
    value: 'id', 
    text: 'name', 
    parentValue: 'pid', 
    hasChildren: 'hasChild' 
  };
}

适用场景： 允许用户在一次操作中选择多个项目，并提供便捷的“全选”选项。使用 selectAllText 作为未选中标签，使用 unSelectAllText 作为已选中标签。

模式 2：自动勾选（父子同步）

@Component({
  template: `<ejs-dropdowntree [fields]='fields' 
                [showCheckBox]='true' 
                [treeSettings]='{ autoCheck: true }'></ejs-dropdowntree>`
})
export class AutoCheckExample {
  public fields = { dataSource: this.data, /* ... */ };
}

适用场景： 确保层级一致性——勾选父项时会自动勾选所有子项；取消勾选最后一个子项时，会取消勾选父项（部分选中时显示中间状态）。

模式 3：使用 OData 加载远程数据

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

@Component({
  template: `<ejs-dropdowntree [fields]='fields'></ejs-dropdowntree>`
})
export class RemoteDataExample {
  public data = new DataManager({
    url: 'url',
    adaptor: new ODataV4Adaptor,
    crossDomain: true
  });
  
  public fields = {
    dataSource: this.data,
    query: new Query().from('Employees').select('EmployeeID,FirstName').take(5),
    value: 'EmployeeID',
    text: 'FirstName',
    hasChildren: 'EmployeeID'
  };
}

适用场景： 从远程服务获取层级数据，减少初始加载量并支持大型数据集。

模式 4：自定义项目显示

@Component({
  template: `<ejs-dropdowntree [fields]='fields' 
                [itemTemplate]='itemTemplate'></ejs-dropdowntree>`
})
export class TemplateExample {
  public itemTemplate = '<div><strong>${name}</strong> - ${type}</div>';
  public fields = { dataSource: this.data, /* ... */ };
}

适用场景： 为每个树项目显示丰富的格式化内容（名称、图标、元数据）。

主要功能

功能	使用场景
层级数据	以父子关系组织项目（类别、部门、文件树）
复选框	启用多选而不影响下拉菜单界面
自动勾选	自动同步父子项的选择状态
远程绑定	从 OData、REST API 或自定义端点获取数据
模板	自定义项目显示、页眉、页脚和选中值格式
无障碍功能	完整的键盘导航、ARIA 属性和屏幕阅读器支持
本地化	支持多种语言和区域格式
全选	单击即可快速选择或取消选择所有项目