syncfusion-angular-dropdownlist

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）
结合Observable数据流使用Async管道
值绑定（基础类型与
```
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

动态添加/移除/清空项
编程式关闭弹窗
级联下拉框实现
自定义分组头部模板
高亮过滤匹配字符
增量搜索行为
自定义远程数据返回结果
远程数据项数量展示
列表项Tooltip
值变更事件处理
列表项图标支持

API Reference

API参考

📄 Read: references/api.md

Complete properties reference with types, defaults, and usage examples
All methods with signatures, parameters, and return types
All events with argument interfaces and usage examples

Interface details:

FieldSettingsModel

ChangeEventArgs

SelectEventArgs

PopupEventArgs

FilteringEventArgs

Quick-reference summary tables for properties, methods, and events

📄 阅读： references/api.md

完整属性参考，包含类型、默认值与使用示例
所有方法的签名、参数与返回类型说明
所有事件的参数接口与使用示例

接口详情：

FieldSettingsModel

、

ChangeEventArgs

、

SelectEventArgs

、

PopupEventArgs

、

FilteringEventArgs

属性、方法、事件的速查表

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://your-api-endpoint.com/Customers', // replace with your own OData or Web API URL
  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://your-api-endpoint.com/Customers', // replace with your own OData or Web API URL
  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`	映射text、value、groupBy、disabled、iconCss字段
`value`	`string \	number \
`placeholder`	`string`	输入框占位文本
`allowFiltering`	`boolean`	开启弹窗内搜索框
`filterType`	`'contains' \	'startsWith' \
`enableVirtualization`	`boolean`	为大列表开启虚拟滚动
`popupHeight` / `popupWidth`	`string \	number`
`enabled`	`boolean`	启用/禁用整个组件
`allowObjectBinding`	`boolean`	支持绑定完整对象作为值
`ignoreCase`	`boolean`	大小写不敏感过滤（默认开启）
`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 ",