syncfusion-angular-drop-down-list

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion Angular DropDownList

The DropDownList component allows users to select a single value from a predefined list. It supports local and remote data sources, filtering, grouping, custom templates, virtualization for large datasets, and full Angular forms integration.

DropDownList组件允许用户从预定义列表中选择单个值。它支持本地和远程数据源、筛选、分组、自定义模板、针对大型数据集的虚拟化，以及完整的Angular表单集成。

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and Angular CLI setup
Installing
```
@syncfusion/ej2-angular-dropdowns
```
CSS/theme imports for Material3
Adding
```
<ejs-dropdownlist>
```
to the template
Basic data binding with
```
[dataSource]
```
Popup height/width configuration
Two-way binding with
```
[(value)]
```

📄 阅读： references/getting-started.md

安装与Angular CLI配置
安装
```
@syncfusion/ej2-angular-dropdowns
```
Material3的CSS/主题导入
在模板中添加
```
<ejs-dropdownlist>
```
使用
```
[dataSource]
```
进行基础数据绑定
弹出框高度/宽度配置
使用
```
[(value)]
```
实现双向绑定

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding primitive arrays (strings, numbers)
Binding arrays of objects with
```
[fields]
```
mapping
Binding to nested/complex objects
Remote data via
```
DataManager
```
(OData, Web API)
Async pipe with Observable data streams
Value binding (primitive and object types with
```
allowObjectBinding
```
)

📄 阅读： references/data-binding.md

绑定原始数组（字符串、数字）
使用
```
[fields]
```
映射绑定对象数组
绑定嵌套/复杂对象
通过
```
DataManager
```
绑定远程数据（OData、Web API）
结合Async pipe与Observable数据流
值绑定（支持原始类型和开启
```
allowObjectBinding
```
后的对象类型）

Filtering

筛选功能

📄 Read: references/filtering.md

Enabling search with
```
[allowFiltering]
```
Using the
```
filtering
```
event and
```
updateData()
```
method
Minimum character threshold before filtering starts
Filter types:
```
contains
```
,
```
startsWith
```
,
```
endsWith
```
Case-sensitive filtering
Diacritics/accent-insensitive filtering
Debounce delay for performance optimization

📄 阅读： references/filtering.md

通过
```
[allowFiltering]
```
启用搜索功能
使用
```
filtering
```
事件和
```
updateData()
```
方法
设置筛选触发的最小字符阈值
筛选类型：
```
contains
```
、
```
startsWith
```
、
```
endsWith
```
区分大小写的筛选
忽略变音符号的筛选
防抖延迟优化性能

Templates

模板定制

📄 Read: references/templates.md

Item template: customize each list item
Value template: customize the selected value display
Group template: customize group header appearance
Header template: static element at popup top
Footer template: static element at popup bottom
No-records template: empty state display
Action failure template: error state display

📄 阅读： references/templates.md

项模板：自定义每个列表项
值模板：自定义选中值的显示样式
分组模板：自定义分组头部外观
头部模板：弹出框顶部的静态元素
底部模板：弹出框底部的静态元素
无数据模板：空状态显示
操作失败模板：错误状态显示

Grouping & Virtualization

分组与虚拟化

📄 Read: references/grouping-and-virtualization.md

Grouping items with
```
groupBy
```
field
Inline and fixed floating group headers
Virtual scrolling with
```
[enableVirtualization]
```
for large lists
Virtual scrolling with remote data
Combining filtering and virtualization
Customizing item count in virtual mode

📄 阅读： references/grouping-and-virtualization.md

使用
```
groupBy
```
字段对项进行分组
内联与固定悬浮分组头部
为大型列表启用
```
[enableVirtualization]
```
实现虚拟滚动
结合远程数据的虚拟滚动
筛选与虚拟化结合使用
自定义虚拟模式下的项数量

Disabled Items & Forms

禁用项与表单集成

📄 Read: references/disabled-items-and-forms.md

Disabling specific items via
```
fields.disabled
```
Dynamic
```
disableItem()
```
method (by value, index, or element)
Disabling the entire component with
```
[enabled]="false"
```
Template-driven forms with
```
[(ngModel)]
```
Reactive forms with
```
FormControl
```
and
```
FormGroup
```

📄 阅读： references/disabled-items-and-forms.md

通过
```
fields.disabled
```
禁用特定项
动态
```
disableItem()
```
方法（按值、索引或元素）
通过
```
[enabled]="false"
```
禁用整个组件
结合
```
[(ngModel)]
```
的模板驱动表单
结合
```
FormControl
```
和
```
FormGroup
```
的响应式表单

Customization & Styling

定制与样式设置

📄 Read: references/customization-and-styling.md

CSS overrides for wrapper, icon, focus states
Outline theme focus customization
Popup appearance and list item styles
Float label and placeholder styling
Mandatory asterisk pattern
Localization with
```
L10n
```
class
RTL (right-to-left) support

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

对容器、图标、焦点状态进行CSS重写
轮廓主题的焦点定制
弹出框外观与列表项样式
浮动标签与占位符样式
必填项星号样式
使用
```
L10n
```
类实现本地化
RTL（从右到左）支持

How-To Recipes

操作指南

📄 Read: references/how-to.md

Add / remove / clear items dynamically
Close popup programmatically
Cascading DropDownLists
Customize group header template
Highlight filtered characters
Incremental search behavior
Modify remote data results
Remote data item count display
Tooltip on list items
Value change event handling
Icon support in list items

📄 阅读： references/how-to.md

动态添加/删除/清空项
以编程方式关闭弹出框
级联DropDownList
自定义分组头部模板
高亮筛选字符
增量搜索行为
修改远程数据结果
远程数据项数量显示
列表项的提示框
值变更事件处理
列表项中的图标支持

Quick Start Example

快速入门示例

typescript

import { Component, OnInit } from '@angular/core';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [DropDownListModule],
  selector: 'app-root',
  template: `
    <ejs-dropdownlist
      id="ddl"
      [dataSource]="sports"
      [fields]="fields"
      placeholder="Select a sport"
      [(value)]="selectedValue"
      (change)="onChange($event)">
    </ejs-dropdownlist>
    <p>Selected: {{ selectedValue }}</p>
  `
})
export class AppComponent implements OnInit {
  public sports: { id: number; name: string }[] = [];
  public fields = { text: 'name', value: 'id' };
  public selectedValue: number = 2;

  ngOnInit() {
    this.sports = [
      { id: 1, name: 'Badminton' },
      { id: 2, name: 'Cricket' },
      { id: 3, name: 'Football' },
      { id: 4, name: 'Tennis' }
    ];
  }

  onChange(args: any) {
    console.log('Selected value:', args.value);
  }
}

typescript

import { Component, OnInit } from '@angular/core';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

@Component({
  standalone: true,
  imports: [DropDownListModule],
  selector: 'app-root',
  template: `
    <ejs-dropdownlist
      id="ddl"
      [dataSource]="sports"
      [fields]="fields"
      placeholder="Select a sport"
      [(value)]="selectedValue"
      (change)="onChange($event)">
    </ejs-dropdownlist>
    <p>Selected: {{ selectedValue }}</p>
  `
})
export class AppComponent implements OnInit {
  public sports: { id: number; name: string }[] = [];
  public fields = { text: 'name', value: 'id' };
  public selectedValue: number = 2;

  ngOnInit() {
    this.sports = [
      { id: 1, name: 'Badminton' },
      { id: 2, name: 'Cricket' },
      { id: 3, name: 'Football' },
      { id: 4, name: 'Tennis' }
    ];
  }

  onChange(args: any) {
    console.log('Selected value:', args.value);
  }
}

Common Patterns

常见模式

Searchable Dropdown

可搜索下拉菜单

typescript

// Enable filtering in template
// <ejs-dropdownlist [allowFiltering]="true" (filtering)="onFilter($event)">
import { FilteringEventArgs } from '@syncfusion/ej2-angular-dropdowns';
import { Query } from '@syncfusion/ej2-data';

onFilter(args: FilteringEventArgs) {
  let query = new Query();
  query = args.text !== '' 
    ? query.where('name', 'contains', args.text, true) 
    : query;
  args.updateData(this.sports, query);
}

typescript

// Enable filtering in template
// <ejs-dropdownlist [allowFiltering]="true" (filtering)="onFilter($event)">
import { FilteringEventArgs } from '@syncfusion/ej2-angular-dropdowns';
import { Query } from '@syncfusion/ej2-data';

onFilter(args: FilteringEventArgs) {
  let query = new Query();
  query = args.text !== '' 
    ? query.where('name', 'contains', args.text, true) 
    : query;
  args.updateData(this.sports, query);
}

Remote Data Dropdown

远程数据下拉菜单

typescript

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

public remoteData: DataManager = new DataManager({
  url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Customers',
  adaptor: new ODataV4Adaptor(),
  crossDomain: true
});
public remoteQuery = new Query().select(['CustomerID', 'ContactName']).take(6);
public remoteFields = { text: 'ContactName', value: 'CustomerID' };
// Template: <ejs-dropdownlist [dataSource]="remoteData" [query]="remoteQuery" [fields]="remoteFields">

typescript

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

public remoteData: DataManager = new DataManager({
  url: 'https://services.odata.org/V4/Northwind/Northwind.svc/Customers',
  adaptor: new ODataV4Adaptor(),
  crossDomain: true
});
public remoteQuery = new Query().select(['CustomerID', 'ContactName']).take(6);
public remoteFields = { text: 'ContactName', value: 'CustomerID' };
// Template: <ejs-dropdownlist [dataSource]="remoteData" [query]="remoteQuery" [fields]="remoteFields">

Reactive Form Integration

响应式表单集成

typescript

import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

// In component:
form = this.fb.group({ sport: ['Cricket', Validators.required] });
// In template:
// <form [formGroup]="form">
//   <ejs-dropdownlist formControlName="sport" [dataSource]="sports"></ejs-dropdownlist>
// </form>

typescript

import { FormBuilder, FormGroup, Validators, ReactiveFormsModule } from '@angular/forms';
import { DropDownListModule } from '@syncfusion/ej2-angular-dropdowns';

// In component:
form = this.fb.group({ sport: ['Cricket', Validators.required] });
// In template:
// <form [formGroup]="form">
//   <ejs-dropdownlist formControlName="sport" [dataSource]="sports"></ejs-dropdownlist>
// </form>

Key Props

核心属性

Property	Type	Description
`dataSource`	`any[] \| DataManager`	Data for the list
`fields`	`FieldSettingsModel`	Maps text, value, groupBy, disabled, iconCss
`value`	`string \| number \| boolean \| object`	Selected value (supports two-way binding)
`placeholder`	`string`	Input placeholder text
`allowFiltering`	`boolean`	Enable search box in popup
`filterType`	`'contains' \| 'startsWith' \| 'endsWith'`	Filter match strategy
`enableVirtualization`	`boolean`	Virtual scrolling for large lists
`popupHeight` / `popupWidth`	`string \| number`	Popup dimensions
`enabled`	`boolean`	Enable/disable entire component
`allowObjectBinding`	`boolean`	Bind full object as value
`ignoreCase`	`boolean`	Case-insensitive filtering (default: true)
`ignoreAccent`	`boolean`	Diacritics-insensitive filtering
`debounceDelay`	`number`	Delay (ms) before filter triggers
`itemTemplate`	`string`	Template for list items
`valueTemplate`	`string`	Template for selected value display
`noRecordsTemplate`	`string`	Empty state message

属性	类型	描述
`dataSource`	`any[] \| DataManager`	列表数据源
`fields`	`FieldSettingsModel`	映射文本、值、groupBy、disabled、iconCss
`value`	`string \| number \| boolean \| object`	选中值（支持双向绑定）
`placeholder`	`string`	输入框占位文本
`allowFiltering`	`boolean`	启用弹出框中的搜索框
`filterType`	`'contains' \| 'startsWith' \| 'endsWith'`	筛选匹配策略
`enableVirtualization`	`boolean`	为大型列表启用虚拟滚动
`popupHeight` / `popupWidth`	`string \| number`	弹出框尺寸
`enabled`	`boolean`	启用/禁用整个组件
`allowObjectBinding`	`boolean`	绑定完整对象作为值
`ignoreCase`	`boolean`	不区分大小写的筛选（默认：true）
`ignoreAccent`	`boolean`	忽略变音符号的筛选
`debounceDelay`	`number`	筛选触发前的延迟（毫秒）
`itemTemplate`	`string`	列表项模板
`valueTemplate`	`string`	选中值显示模板
`noRecordsTemplate`	`string`	空状态提示文本

Common Use Cases

常见使用场景

Form field with validation → See references/disabled-items-and-forms.md

Large list (1000+ items) → Enable

[enableVirtualization]="true"

— see references/grouping-and-virtualization.md

Country/State/City cascading → See references/how-to.md

Custom item rendering (icons, multi-column) → See references/templates.md

Remote API data → See references/data-binding.md

带验证的表单字段 → 查看references/disabled-items-and-forms.md

大型列表（1000+项） → 启用

[enableVirtualization]="true"

— 查看references/grouping-and-virtualization.md

国家/州/城市级联 → 查看references/how-to.md

自定义项渲染（图标、多列）→ 查看references/templates.md

远程API数据 → 查看references/data-binding.md