syncfusion-react-dropdownlist

用途

Syncfusion React DropDownList 是一个 React 组件，用于从预定义的值列表中让用户选择单个值。适用于添加下拉框、选择框等单选场景。

主要能力

数据绑定：支持绑定字符串、数字等原始类型数组，也支持绑定 JSON 对象数组，并通过 fields 映射 text、value、groupBy、iconCss、disabled 等字段。支持使用 DataManager 进行远程数据绑定，适配 OData、ODataV4、WebAPI。
值绑定：可预选值，支持原始类型与复杂对象绑定，可通过 fields.disabled 禁用单个选项。
筛选：启用 allowFiltering 实现输入即搜索；通过 filtering 事件配合 updateData 自定义筛选逻辑；支持 startswith、contains、endsWith 及大小写敏感选项；支持多字段筛选（使用 Predicate 的 .or()）；支持远程/服务端筛选、变音符号过滤（ignoreAccent）、防抖延迟、高亮匹配文本。
分组与模板：通过 groupBy 字段分组，支持固定与内联组头、自定义组头模板、项模板、选中值模板、页眉页脚模板、无记录与操作失败模板。
功能与配置：排序（升序、降序）、大数据量虚拟滚动（enableVirtualization）、弹出层可缩放（allowResize）、增量搜索、清除按钮、只读、禁用、RTL 支持、Preact 用法。
无障碍、样式与本地化：符合 WCAG 2.2 / Section 508，支持键盘导航、ARIA 角色与属性；cssClass 属性可设置实例级 CSS 类，支持多个类、条件类及内置工具类（e-error、e-success）；可自定义包装器、图标、弹出层、列表项、占位符的 CSS 类；提供 tailwind3、material3、bootstrap5、fluent2 主题；支持本地化（L10n、noRecordsTemplate、actionFailureTemplate）与 RTL 布局（enableRtl）。

使用方式

安装：

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

注意：该包为第三方包，建议在 package.json 中固定到已验证的具体版本，并通过 lockfile 校验完整性后再部署到生产环境。

添加 CSS 导入（在 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"
    />
  );
}

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	弹出列表高度（默认 auto）
popupWidth	string	弹出列表宽度（默认与输入框一致）
sortOrder	SortOrder	'None'、'Ascending'、'Descending'
enableVirtualization	boolean	大数据量虚拟滚动
allowResize	boolean	用户可调整弹出层大小
enabled	boolean	启用/禁用整个组件
readonly	boolean	只读模式
showClearButton	boolean	显示 ✕ 按钮清除选择
enableRtl	boolean	从右到左布局

适用场景

简单静态列表：向 dataSource 传入 string[] 即可。
来自 API 的数据：使用 DataManager 配合 WebApiAdaptor。注意远程适配器会在运行时发起出站 HTTP 请求，需确保端点可信、已认证且不暴露敏感数据。
输入即搜索/筛选：设置 allowFiltering={true} 并处理 filtering 事件。
分类项：映射 groupBy 字段。
自定义项布局：使用 itemTemplate。
大数据集（1 万条以上）：启用 enableVirtualization 并注入 VirtualScroll。
级联（依赖）下拉框：在第一个下拉框的 change 事件中重新加载第二个下拉框的 dataSource。

限制与注意事项

使用 DataManager 的远程适配器（ODataAdaptor、ODataV4Adaptor、WebApiAdaptor）会在运行时发起出站 HTTP 请求，生产环境使用前需确保所有远程端点可信、已认证且不暴露敏感数据。
@syncfusion/ej2-react-dropdowns 是 Syncfusion Inc. 发布的第三方包，建议在 package.json 中固定到具体已验证版本，并通过 lockfile 校验完整性后再部署到生产环境。
自定义筛选处理函数中应始终设置 args.preventDefaultAction = true，以防止内置筛选与自定义逻辑同时运行。
其他未在资料中提及的功能、收费、价格、平台或效果暂未提供。