syncfusion-angular-dropdowntree

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Angular Dropdown Tree

实现Syncfusion Angular Dropdown Tree组件

The Dropdown Tree component allows you to select single or multiple values from hierarchical data in a tree-like structure. It provides essential features like data binding, checkboxes, templates, and accessibility, making it ideal for displaying categorized selections, organizational hierarchies, and nested data structures.

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

When to Use This Skill

何时使用该组件

Use the Dropdown Tree component when you need to:

Hierarchical Selection - Allow users to select from nested, tree-structured data (categories, file hierarchies, organizational trees)
Multi-Selection - Enable checkbox-based selection of multiple items with optional auto-check (parent-child sync)
Dynamic Data - Bind local arrays, self-referential structures, or remote OData/REST endpoints
Customized Display - Use item templates, value templates, headers, and footers for rich UI customization
Large Datasets - Support remote data with lazy loading to optimize performance
Localization - Adapt component text and messages for different cultures and languages

当你需要以下功能时，可使用Dropdown Tree组件：

层级选择 - 允许用户从嵌套的树形结构数据（类别、文件层级、组织架构树）中进行选择
多选功能 - 启用基于复选框的多项选择，可选择自动勾选（父子同步）
动态数据 - 绑定本地数组、自引用结构或远程OData/REST端点
自定义展示 - 使用项模板、值模板、页眉和页脚实现丰富的UI自定义
大型数据集 - 支持带懒加载的远程数据，优化性能
本地化 - 适配不同文化和语言的组件文本与提示信息

Component Overview

组件概述

The Dropdown Tree provides a compact dropdown input that expands to show a full tree structure with powerful filtering, selection, and templating capabilities. Unlike flat dropdowns, it maintains hierarchical relationships, enabling intuitive navigation through multi-level data.

Key Characteristics:

Single or multiple item selection
Checkbox-based multi-selection with optional auto-check
Local hierarchical and self-referential data binding
Remote data binding with DataManager (OData, ODataV4, WebAPI)
Rich templating: items, values, headers, footers, no-records, action-failure
Built-in accessibility with keyboard navigation and ARIA attributes
Full localization support

Dropdown Tree提供了一个紧凑的下拉输入框，展开后可显示完整的树形结构，具备强大的筛选、选择和模板功能。与扁平下拉框不同，它能维护层级关系，让用户可以直观地导航多层级数据。

核心特性：

单个或多个项选择
基于复选框的多选，支持可选自动勾选
本地层级数据和自引用数据绑定
结合DataManager的远程数据绑定（OData、ODataV4、WebAPI）
丰富的模板：项、值、页眉、页脚、无数据、加载失败
内置无障碍支持，包含键盘导航和ARIA属性
完整的本地化支持

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Dependencies and package setup
Angular CLI configuration
Module registration (@syncfusion/ej2-angular-dropdowns)
CSS imports and theme configuration
Basic component integration
First working example with local data

📄 阅读： references/getting-started.md

依赖项与包设置
Angular CLI配置
模块注册（@syncfusion/ej2-angular-dropdowns）
CSS导入与主题配置
基础组件集成
基于本地数据的首个可运行示例

Data Binding

数据绑定

📄 Read: references/data-binding.md

Hierarchical data structure (nested arrays)
Self-referential data binding (flat arrays with parentValue)
Remote data with DataManager
OData and ODataV4 adaptors
WebAPI adaptor configuration
Query-based filtering

📄 阅读： references/data-binding.md

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

Checkbox Features

复选框功能

📄 Read: references/checkbox-features.md

Enable checkboxes with showCheckBox property
Multi-selection without UI disruption
Auto-check hierarchical behavior (parent-child sync)
Select All feature (showSelectAll with custom labels)
Checkbox state synchronization
Intermediate states (partially checked)

📄 阅读： references/checkbox-features.md

使用showCheckBox属性启用复选框
不干扰UI的多选功能
自动勾选层级行为（父子同步）
全选功能（showSelectAll支持自定义标签）
复选框状态同步
中间状态（部分勾选）

Templates and Customization

模板与自定义

📄 Read: references/templates.md

Item template for custom tree item rendering
Value template for selected item display
Header and footer templates
No records and action failure templates
Custom display template for multi-selection (Custom mode)
Template expressions and interpolation

📄 阅读： references/templates.md

用于自定义树形项渲染的项模板
用于已选项展示的值模板
页眉和页脚模板
无数据和加载失败模板
多选的自定义展示模板（自定义模式）
模板表达式与插值

Localization

本地化

📄 Read: references/localization.md

Supported localization keys and default messages
Setting locale and culture
Customizing locale-specific strings
Key messages: noRecordsTemplate, actionFailureTemplate, overflowCountTemplate, totalCountTemplate
Multi-language configuration

📄 阅读： references/localization.md

支持的本地化键与默认提示信息
设置区域与文化
自定义区域特定字符串
核心提示信息：noRecordsTemplate、actionFailureTemplate、overflowCountTemplate、totalCountTemplate
多语言配置

API Reference

API参考

📄 Read: references/api-reference.md

Core properties and field mappings
TreeSettings configuration options
Common events and callbacks
Best practices for property configuration
Performance optimization tips

📄 阅读： references/api-reference.md

核心属性与字段映射
TreeSettings配置选项
通用事件与回调
属性配置最佳实践
性能优化技巧

Methods and Events

方法与事件

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

Component methods: showPopup(), hidePopup(), refresh(), clearSelection(), expandAll(), collapseAll()
Selection events: change, select
Popup events: open, close, beforeOpen
Data events: dataBound, actionFailure, filtering
Lifecycle events: created, destroyed
User interaction events: focus, blur, keyPress
Event arguments and signatures
Complete working examples

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

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

Quick Start Example

快速入门示例

Here's a minimal working example with hierarchical data:

typescript

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' 
  };
}

以下是一个基于层级数据的最简可运行示例：

typescript

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' 
  };
}

Common Patterns

常见模式

Pattern 1: Multi-Selection with Checkboxes

模式1：带复选框的多选

typescript

@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' 
  };
}

When to use: Allow users to select multiple items in a single interaction, with convenient "Select All" option. Use

selectAllText

for unchecked label and

unSelectAllText

for checked label.

typescript

@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

作为已勾选状态的标签。

Pattern 2: Auto-Check (Parent-Child Sync)

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

typescript

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

When to use: Enforce hierarchical consistency—checking a parent automatically checks all children, and unchecking the last child unchecks the parent (intermediate state for partial selection).

typescript

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

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

Pattern 3: Remote Data with OData

模式3：基于OData的远程数据

typescript

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

@Component({
  template: `<ejs-dropdowntree [fields]='fields'></ejs-dropdowntree>`
})
export class RemoteDataExample {
  public data = new DataManager({
    url: 'https://services.odata.org/V4/Northwind/Northwind.svc',
    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'
  };
}

When to use: Fetch hierarchical data from a remote server, reducing initial load and supporting large datasets.

typescript

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

@Component({
  template: `<ejs-dropdowntree [fields]='fields'></ejs-dropdowntree>`
})
export class RemoteDataExample {
  public data = new DataManager({
    url: 'https://services.odata.org/V4/Northwind/Northwind.svc',
    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'
  };
}

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

Pattern 4: Custom Item Display

模式4：自定义项展示

typescript

@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, /* ... */ };
}

When to use: Display rich, formatted content for each tree item (names, icons, metadata).

typescript

@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, /* ... */ };
}

适用场景： 为每个树形项展示富格式内容（名称、图标、元数据）。

Key Features

核心功能

Feature	Use Case
Hierarchical Data	Organize items in parent-child relationships (categories, departments, file trees)
Checkboxes	Enable multi-selection without affecting dropdown UI
Auto-Check	Synchronize parent-child selection states automatically
Remote Binding	Fetch data from OData, REST APIs, or custom endpoints
Templates	Customize item display, headers, footers, and selected value format
Accessibility	Full keyboard navigation, ARIA attributes, screen reader support
Localization	Support for multiple languages and regional formats
Select All	Quickly select or deselect all items with a single click

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