syncfusion-react-dropdownlist

Syncfusion React DropDownList

DropDownList 组件提供一组预定义值，供用户选择单个值。它支持本地和远程数据绑定、筛选、分组、自定义模板、虚拟滚动、无障碍功能和丰富的自定义选项。

导航指南

入门

📄 阅读： references/getting-started.md

• 安装和软件包设置（@syncfusion/ej2-react-dropdowns）
• 使用 tailwind3 主题导入 CSS
• 基本 DropDownList（函数组件和类组件）
• 绑定数据源
• 配置弹出窗口的高度和宽度

数据绑定与值绑定

📄 阅读： references/data-binding.md

• 绑定基本类型数组（字符串、数字）
• 使用 fields 映射（text、value、groupBy、iconCss）绑定 JSON 对象数组
• 使用 DataManager 连接远程数据（OData、ODataV4、WebAPI 适配器）
• 值绑定：预选值、绑定基本类型与复杂对象
• 使用 fields.disabled 禁用单个项

⚠️ 网络提示： 在远程适配器（ODataAdaptor、ODataV4Adaptor、WebApiAdaptor）中使用 DataManager，会使组件在运行时发起出站 HTTP 请求。在生产环境中接入远程数据绑定之前，请确保所有远程端点均可信、已通过身份验证，且不会暴露敏感数据。

筛选

📄 阅读： references/filtering.md

• 启用 allowFiltering，实现输入即搜索
• 使用 updateData 处理 filtering 事件
• 阻止默认筛选——在自定义处理程序中始终设置 args.preventDefaultAction = true
• 筛选类型：startswith、contains、endsWith，以及区分大小写的选项
• 按多个字段筛选——使用 Predicate 和 .or()，将输入文本与 text 和 value 字段（或任意字段组合）进行匹配
• 远程／服务器端筛选及最少字符数限制
• 变音符号筛选（ignoreAccent）、防抖延迟
• 高亮显示筛选文本、自定义搜索逻辑

分组与模板

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

• 使用 groupBy 字段对项进行分组
• 固定和内嵌分组标题
• 自定义分组标题模板
• 项模板、值（已选项）模板
• 标题和页脚模板
• 无记录和操作失败模板

功能与配置

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

• 排序（sortOrder：升序、降序）
• 对大型列表启用虚拟滚动（enableVirtualization）
• 调整弹出窗口大小（allowResize）
• 增量搜索、清除按钮、只读、禁用
• RTL 支持、使用 Preact

无障碍、样式与本地化

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

• 符合 WCAG 2.2 / Section 508 标准
• 键盘导航快捷键
• ARIA 角色和属性
• cssClass 属性——作用于单个实例的 CSS 类、多个类、条件类、内置实用类（e-error、e-success）
• CSS 类自定义（包装器、图标、弹出窗口、列表项、占位符）
• 主题（tailwind3、material3、bootstrap5、fluent2）
• 本地化（L10n、noRecordsTemplate、actionFailureTemplate）
• RTL 布局（enableRtl）

API 参考

📄 阅读： references/api.md

• 完整的属性参考，包含类型、默认值和使用示例
• 所有方法的签名、参数和返回类型
• 所有事件的参数接口和使用示例
• 接口详情：FieldSettingsModel、ChangeEventArgs、SelectEventArgs、PopupEventArgs、FilteringEventArgs
• 属性、方法和事件的快速参考汇总表

操作指南模式

📄 阅读： references/how-to.md

• 动态添加、移除或修改项目
• 级联（依赖）下拉列表
• 多个级联下拉列表
• 远程数据操作指南
• 滚动时关闭弹出窗口、为项目添加工具提示、在项目中添加图标
• 值更改事件、清除所选值

---

快速入门示例

步骤 1 — 安装包，使用你的包管理器安装（安装前，请在官方 Syncfusion npm 注册表中验证该包）：

npm install @syncfusion/ej2-react-dropdowns --save

⚠️ 供应链提示： @syncfusion/ej2-react-dropdowns 是由 Syncfusion Inc. 发布的第三方包。请始终在 package.json 中固定到经过验证的特定版本（例如，"@syncfusion/ej2-react-dropdowns": "27.x.x"），并在部署到生产环境之前，通过锁定文件（package-lock.json 或 yarn.lock）验证其完整性。

步骤 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";

步骤 3 — 使用组件：

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"
    />
  );
}

常见模式

使用字段映射 JSON 对象数据

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"
    />
  );
}

筛选（输入时搜索）

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) {
    args.preventDefaultAction = true; // prevent built-in filter from running alongside custom logic
    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"
    />
  );
}

预选值

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

分组项目

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" />

主要属性

属性	类型	用途
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	从右向左布局

常见使用场景

简单静态列表 → 将 string[] 传给 dataSource 即可。

来自 API 的数据 → 使用 DataManager 和 WebApiAdaptor；阅读 references/data-binding.md。⚠️ 远程适配器会建立出站 HTTP 连接，请确保端点可信。

在用户输入时搜索/筛选 → 设置 allowFiltering={true}，并处理 filtering 事件；阅读 references/filtering.md。

分类项目 → 映射 groupBy 字段；阅读 references/grouping-and-templates.md。

自定义项目布局 → 使用 itemTemplate；阅读 references/grouping-and-templates.md。

大型数据集（10k+ 项） → 启用 enableVirtualization 并注入 VirtualScroll；阅读 references/features-and-configuration.md。

依赖下拉列表 → 在第一个下拉列表的 change 事件中重新加载第二个下拉列表的 dataSource；阅读 references/how-to.md。