syncfusion-react-dropdownlist

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Syncfusion React DropDownList

Syncfusion React DropDownList组件

The DropDownList component provides a list of predefined values from which users can select a single value. It supports local and remote data binding, filtering, grouping, custom templates, virtual scrolling, accessibility, and rich customization.

DropDownList组件提供预定义值列表，用户可从中选择单个值。它支持本地和远程数据绑定、过滤、分组、自定义模板、虚拟滚动、可访问性以及丰富的自定义功能。

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup (
```
@syncfusion/ej2-react-dropdowns
```
)
CSS imports with tailwind3 theme
Basic DropDownList (functional and class components)
Binding a data source
Configuring popup height and width

📄 阅读： references/getting-started.md

安装和包设置（
```
@syncfusion/ej2-react-dropdowns
```
）
导入带tailwind3主题的CSS
基础DropDownList（函数组件和类组件）
绑定数据源
配置弹出框高度和宽度

Data Binding & Value Binding

数据绑定与值绑定

📄 Read: references/data-binding.md

Binding primitive arrays (strings, numbers)
Binding JSON object arrays with
```
fields
```
mapping (
```
text
```
,
```
value
```
,
```
groupBy
```
,
```
iconCss
```
)
Remote data with
```
DataManager
```
(OData, ODataV4, WebAPI adaptors)
Value binding: preselecting values, binding primitive vs. complex objects
Disabling individual items with
```
fields.disabled
```

📄 阅读： references/data-binding.md

绑定原始数组（字符串、数字）
使用
```
fields
```
映射绑定JSON对象数组（
```
text
```
、
```
value
```
、
```
groupBy
```
、
```
iconCss
```
）
结合
```
DataManager
```
实现远程数据绑定（OData、ODataV4、WebAPI适配器）
值绑定：预选择值、绑定原始类型与复杂对象
使用
```
fields.disabled
```
禁用单个选项

Filtering

过滤功能

📄 Read: references/filtering.md

Enabling
```
allowFiltering
```
for search-as-you-type
Handling the
```
filtering
```
event with
```
updateData
```
Filter types:
```
startswith
```
,
```
contains
```
, case-sensitive options
Remote/server-side filtering
Minimum search length (
```
minLength
```
)
Highlight filtered text, custom search logic

📄 阅读： references/filtering.md

启用
```
allowFiltering
```
实现输入时搜索
使用
```
updateData
```
处理
```
filtering
```
事件
过滤类型：
```
startswith
```
、
```
contains
```
、大小写敏感选项
远程/服务器端过滤
最小搜索长度（
```
minLength
```
）
高亮过滤文本、自定义搜索逻辑

Grouping & Templates

分组与模板

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

Grouping items with the
```
groupBy
```
field
Fixed and inline group headers
Custom group header template
Item template, value (selected) template
Header and footer templates
No-records and action-failure templates

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

使用
```
groupBy
```
字段对选项进行分组
固定和内联组标题
自定义组标题模板
选项模板、选中值模板
头部和底部模板
无数据和操作失败模板

Features & Configuration

功能与配置

📄 Read: references/features-and-configuration.md

Sorting (
```
sortOrder
```
: ascending, descending)
Virtual scrolling for large lists (
```
enableVirtualization
```
)
Popup resize (
```
allowResize
```
)
Incremental search, clear button, readonly, disabled
RTL support, Preact usage

📄 阅读： references/features-and-configuration.md

排序（
```
sortOrder
```
：升序、降序）
针对大型列表的虚拟滚动（
```
enableVirtualization
```
）
弹出框可调整大小（
```
allowResize
```
）
增量搜索、清除按钮、只读模式、禁用状态
RTL布局支持、Preact使用

Accessibility, Styling & Localization

可访问性、样式与本地化

📄 Read: references/accessibility-styling-localization.md

WCAG 2.2 / Section 508 compliance
Keyboard navigation shortcuts
ARIA roles and attributes
CSS class customization

Localization (

L10n

noRecordsTemplate

actionFailureTemplate

)

📄 阅读： references/accessibility-styling-localization.md

符合WCAG 2.2 / Section 508标准
键盘导航快捷键
ARIA角色与属性
CSS类自定义

本地化（

L10n

、

noRecordsTemplate

、

actionFailureTemplate

）

How-To Patterns

操作指南

📄 Read: references/how-to.md

Add, remove, or modify items dynamically
Cascading (dependent) dropdowns
Multiple cascading dropdowns
Remote data how-to
Close popup on scroll, tooltip on items, icons in items
Value change event, clearing selected value

📄 阅读： references/how-to.md

动态添加、删除或修改选项
级联（依赖）下拉菜单
多层级联下拉菜单
远程数据使用指南
滚动时关闭弹出框、选项提示、选项图标
值变更事件、清除选中值

Quick Start Example

快速入门示例

tsx

// 1. Install
// npm install @syncfusion/ej2-react-dropdowns --save

// 2. CSS in src/App.css
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
import './App.css';

export default function App() {
  const sportsData: string[] = ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis'];

  return (
    <DropDownListComponent
      id="ddlelement"
      dataSource={sportsData}
      placeholder="Select a game"
    />
  );
}

tsx

// 1. 安装
// npm install @syncfusion/ej2-react-dropdowns --save

// 2. 在src/App.css中引入CSS
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-inputs/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';
import './App.css';

export default function App() {
  const sportsData: string[] = ['Badminton', 'Cricket', 'Football', 'Golf', 'Tennis'];

  return (
    <DropDownListComponent
      id="ddlelement"
      dataSource={sportsData}
      placeholder="Select a game"
    />
  );
}

Common Patterns

常见模式

JSON Object Data with Fields Mapping

带字段映射的JSON对象数据

tsx

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const countryData = [
    { Id: 'au', Country: 'Australia' },
    { Id: 'br', Country: 'Brazil' },
    { Id: 'cn', Country: 'China' },
    { Id: 'in', Country: 'India' },
  ];
  const fields = { text: 'Country', value: 'Id' };

  return (
    <DropDownListComponent
      dataSource={countryData}
      fields={fields}
      placeholder="Select a country"
    />
  );
}

tsx

import { DropDownListComponent } from '@syncfusion/ej2-react-dropdowns';

export default function App() {
  const countryData = [
    { Id: 'au', Country: 'Australia' },
    { Id: 'br', Country: 'Brazil' },
    { Id: 'cn', Country: 'China' },
    { Id: 'in', Country: 'India' },
  ];
  const fields = { text: 'Country', value: 'Id' };

  return (
    <DropDownListComponent
      dataSource={countryData}
      fields={fields}
      placeholder="Select a country"
    />
  );
}

Filtering (Search-as-you-type)

过滤（输入时搜索）

tsx

import { DropDownListComponent, FilteringEventArgs } from '@syncfusion/ej2-react-dropdowns';
import { Query } from '@syncfusion/ej2-data';

export default function App() {
  const searchData = [
    { Index: 's1', Country: 'Alaska' },
    { Index: 's2', Country: 'California' },
    { Index: 's3', Country: 'Florida' },
  ];
  const fields = { text: 'Country', value: 'Index' };

  function onFiltering(args: FilteringEventArgs) {
    let query = new Query();
    query = args.text !== '' ? query.where('Country', 'startswith', args.text, true) : query;
    args.updateData(searchData, query);
  }

  return (
    <DropDownListComponent
      dataSource={searchData}
      fields={fields}
      allowFiltering={true}
      filtering={onFiltering}
      placeholder="Select a country"
    />
  );
}

tsx

import { DropDownListComponent, FilteringEventArgs } from '@syncfusion/ej2-react-dropdowns';
import { Query } from '@syncfusion/ej2-data';

export default function App() {
  const searchData = [
    { Index: 's1', Country: 'Alaska' },
    { Index: 's2', Country: 'California' },
    { Index: 's3', Country: 'Florida' },
  ];
  const fields = { text: 'Country', value: 'Index' };

  function onFiltering(args: FilteringEventArgs) {
    let query = new Query();
    query = args.text !== '' ? query.where('Country', 'startswith', args.text, true) : query;
    args.updateData(searchData, query);
  }

  return (
    <DropDownListComponent
      dataSource={searchData}
      fields={fields}
      allowFiltering={true}
      filtering={onFiltering}
      placeholder="Select a country"
    />
  );
}

Preselect a Value

预选择值

tsx

<DropDownListComponent
  dataSource={sportsData}
  value="Cricket"
  placeholder="Select a game"
/>

tsx

<DropDownListComponent
  dataSource={sportsData}
  value="Cricket"
  placeholder="Select a game"
/>

Grouped Items

分组选项

tsx

const vegetableData = [
  { Vegetable: 'Cabbage', Category: 'Leafy and Salad', Id: 'item1' },
  { Vegetable: 'Chickpea', Category: 'Beans', Id: 'item6' },
  { Vegetable: 'Garlic',   Category: 'Bulb and Stem', Id: 'item9' },
];
const fields = { groupBy: 'Category', text: 'Vegetable', value: 'Id' };

<DropDownListComponent dataSource={vegetableData} fields={fields} placeholder="Select a vegetable" />

tsx

const vegetableData = [
  { Vegetable: 'Cabbage', Category: 'Leafy and Salad', Id: 'item1' },
  { Vegetable: 'Chickpea', Category: 'Beans', Id: 'item6' },
  { Vegetable: 'Garlic',   Category: 'Bulb and Stem', Id: 'item9' },
];
const fields = { groupBy: 'Category', text: 'Vegetable', value: 'Id' };

<DropDownListComponent dataSource={vegetableData} fields={fields} placeholder="Select a vegetable" />

Key Props

关键属性

Prop	Type	Purpose
`dataSource`	`any[] \| DataManager`	Data for the list items
`fields`	`FieldSettingsModel`	Maps `text` , `value` , `groupBy` , `iconCss` , `disabled`
`value`	`string \| number`	Selected/preselected value
`placeholder`	`string`	Input placeholder text
`allowFiltering`	`boolean`	Enables search filtering
`filtering`	`event`	Handler for custom filter logic
`popupHeight`	`string`	Popup list height (default auto)
`popupWidth`	`string`	Popup list width (default matches input)
`sortOrder`	`SortOrder`	`'None'` , `'Ascending'` , `'Descending'`
`enableVirtualization`	`boolean`	Virtual scroll for large data
`allowResize`	`boolean`	User-resizable popup
`enabled`	`boolean`	Enable/disable entire component
`readonly`	`boolean`	Read-only mode
`showClearButton`	`boolean`	Shows ✕ button to clear selection
`enableRtl`	`boolean`	Right-to-left layout

属性	类型	用途
`dataSource`	`any[] \| DataManager`	列表选项的数据源
`fields`	`FieldSettingsModel`	映射 `text` 、 `value` 、 `groupBy` 、 `iconCss` 、 `disabled`
`value`	`string \| number`	选中/预选中的值
`placeholder`	`string`	输入框占位文本
`allowFiltering`	`boolean`	启用搜索过滤
`filtering`	`event`	自定义过滤逻辑的处理函数
`popupHeight`	`string`	弹出列表高度（默认自动）
`popupWidth`	`string`	弹出列表宽度（默认匹配输入框）
`sortOrder`	`SortOrder`	`'None'` 、 `'Ascending'` 、 `'Descending'`
`enableVirtualization`	`boolean`	针对大数据的虚拟滚动
`allowResize`	`boolean`	用户可调整弹出框大小
`enabled`	`boolean`	启用/禁用整个组件
`readonly`	`boolean`	只读模式
`showClearButton`	`boolean`	显示✕按钮以清除选中值
`enableRtl`	`boolean`	从右到左布局

Common Use Cases

常见使用场景

Simple static list → Pass

string[]

dataSource

, done.

Data from API → Use

DataManager

with

WebApiAdaptor

; read

references/data-binding.md

Search/filter as user types → Set

allowFiltering={true}

, handle

filtering

event; read

references/filtering.md

Categorized items → Map

groupBy

field; read

references/grouping-and-templates.md

Custom item layout → Use

itemTemplate

; read

references/grouping-and-templates.md

Large dataset (10k+ items) → Enable

enableVirtualization

+ inject

VirtualScroll

; read

references/features-and-configuration.md

Dependent dropdowns → Reload second dropdown's

dataSource

on first's

change

event; read

references/how-to.md

简单静态列表 → 将

string[]

传入

dataSource

即可。

来自API的数据 → 使用

DataManager

搭配

WebApiAdaptor

；请阅读

references/data-binding.md

。

用户输入时搜索/过滤 → 设置

allowFiltering={true}

，处理

filtering

事件；请阅读

references/filtering.md

。

分类选项 → 映射

groupBy

字段；请阅读

references/grouping-and-templates.md

。

自定义选项布局 → 使用

itemTemplate

；请阅读

references/grouping-and-templates.md

。

大型数据集（10000+条） → 启用

enableVirtualization

并注入

VirtualScroll

；请阅读

references/features-and-configuration.md

。

依赖下拉菜单 → 在第一个下拉菜单的

change

事件中重新加载第二个下拉菜单的

dataSource

；请阅读

references/how-to.md

。