syncfusion-react-dropdowns

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React Dropdowns

实现Syncfusion React下拉组件

AutoComplete

AutoComplete组件

The AutoComplete component provides a matched suggestion list as the user types into an input field, allowing selection from the filtered results. It supports local and remote data, rich filtering options, templates, grouping, virtualization, and full accessibility.

AutoComplete组件会在用户输入内容时显示匹配的建议列表，用户可从筛选后的结果中进行选择。它支持本地和远程数据、丰富的筛选选项、模板、分组、虚拟化以及完整的无障碍功能。

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Package installation (
```
@syncfusion/ej2-react-dropdowns
```
)
CSS imports and theme configuration
Basic component setup (functional and class components)
Binding a simple string array
Configuring popup height and width (
```
popupHeight
```
,
```
popupWidth
```
)

📄 阅读： references/getting-started.md

包安装（
```
@syncfusion/ej2-react-dropdowns
```
）
CSS导入与主题配置
基础组件设置（函数式与类组件）
绑定简单字符串数组
配置弹窗高度与宽度（
```
popupHeight
```
、
```
popupWidth
```
）

Data Binding

数据绑定

📄 Read: references/data-binding.md

Array of strings or numbers
Array of objects with
```
fields
```
mapping (
```
value
```
,
```
groupBy
```
,
```
iconCss
```
)
Array of complex/nested objects (dot-notation field mapping)
Remote data with
```
DataManager
```
(ODataV4Adaptor, WebApiAdaptor)
Using
```
query
```
property to filter/select remote data
```
sortOrder
```
for alphabetical ordering

📄 阅读： references/data-binding.md

字符串或数字数组
带
```
fields
```
映射的对象数组（
```
value
```
、
```
groupBy
```
、
```
iconCss
```
）
复杂/嵌套对象数组（点符号字段映射）
使用
```
DataManager
```
的远程数据（ODataV4Adaptor、WebApiAdaptor）
使用
```
query
```
属性筛选/选择远程数据
用于字母排序的
```
sortOrder
```

Filtering

筛选

📄 Read: references/filtering.md

Filter types:
```
StartsWith
```
,
```
EndsWith
```
,
```
Contains
```
```
suggestionCount
```
– limit number of suggestions
```
minLength
```
– minimum characters before search triggers
```
ignoreCase
```
– case-sensitive filtering
```
ignoreAccent
```
– diacritics filtering
```
debounceDelay
```
– delay filtering to reduce requests
Custom filtering with the
```
filtering
```
event

📄 阅读： references/filtering.md

筛选类型：
```
StartsWith
```
、
```
EndsWith
```
、
```
Contains
```
```
suggestionCount
```
– 限制建议数量
```
minLength
```
– 触发搜索的最小字符数
```
ignoreCase
```
– 区分大小写的筛选
```
ignoreAccent
```
– 带变音符号的筛选
```
debounceDelay
```
– 延迟筛选以减少请求
使用
```
filtering
```
事件进行自定义筛选

Grouping

分组

📄 Read: references/grouping.md

Grouping items using
```
fields.groupBy
```
Fixed and inline group headers
Custom group header with
```
groupTemplate
```

📄 阅读： references/grouping.md

使用
```
fields.groupBy
```
对项目进行分组
固定和内联分组标题
使用
```
groupTemplate
```
自定义分组标题

Templates

模板

📄 Read: references/templates.md

```
itemTemplate
```
– customize each list item
```
groupTemplate
```
– customize group header
```
headerTemplate
```
– static popup header
```
footerTemplate
```
– static popup footer
```
noRecordsTemplate
```
– message when no data found
```
actionFailureTemplate
```
– message on remote fetch failure

📄 阅读： references/templates.md

```
itemTemplate
```
– 自定义每个列表项
```
groupTemplate
```
– 自定义分组标题
```
headerTemplate
```
– 静态弹窗头部
```
footerTemplate
```
– 静态弹窗底部
```
noRecordsTemplate
```
– 无数据时的提示信息
```
actionFailureTemplate
```
– 远程数据获取失败时的提示信息

Value Binding

值绑定

📄 Read: references/value-binding.md

Binding primitive values (string, number)
Object binding with
```
allowObjectBinding
```
Presetting selected values with the
```
value
```
property

📄 阅读： references/value-binding.md

绑定原始值（字符串、数字）
使用
```
allowObjectBinding
```
绑定对象
使用
```
value
```
属性预设选中值

Virtualization

虚拟化

📄 Read: references/virtual-scroll.md

```
enableVirtualization
```
for large datasets
Injecting the
```
VirtualScroll
```
service
Virtual scrolling with local data, remote data, and grouping
Customizing item count with
```
query.take()
```

📄 阅读： references/virtual-scroll.md

针对大型数据集启用
```
enableVirtualization
```
注入
```
VirtualScroll
```
服务
本地数据、远程数据和分组场景下的虚拟滚动
使用
```
query.take()
```
自定义项目数量

Disabled Items

禁用项

📄 Read: references/disabled-items.md

Disabling items via
```
fields.disabled
```
```
disableItem
```
method for dynamic disabling
Disabling the entire component with
```
enabled={false}
```

📄 阅读： references/disabled-items.md

通过
```
fields.disabled
```
禁用项
使用
```
disableItem
```
方法动态禁用
使用
```
enabled={false}
```
禁用整个组件

Accessibility and Localization

无障碍与本地化

📄 Read: references/accessibility-localization.md

WAI-ARIA roles and attributes
Keyboard navigation shortcuts
RTL support (
```
enableRtl
```
)
Localization with
```
L10n
```
(noRecordsTemplate, actionFailureTemplate text)
WCAG 2.2 compliance overview

📄 阅读： references/accessibility-localization.md

WAI-ARIA角色与属性
键盘导航快捷键
RTL支持（
```
enableRtl
```
）
使用
```
L10n
```
进行本地化（noRecordsTemplate、actionFailureTemplate文本）
WCAG 2.2合规概述

Styling and Customization

样式与自定义

📄 Read: references/styling.md

CSS class targets for wrapper, icon, focus, placeholder, selection
Float label customization
Popup item appearance
```
cssClass
```
property for custom class injection
Popup resize (
```
allowResize
```
)
Mandatory asterisk styling

📄 阅读： references/styling.md

包装器、图标、焦点、占位符、选中状态的CSS类目标
浮动标签自定义
弹窗项外观
用于注入自定义类的
```
cssClass
```
属性
弹窗调整大小（
```
allowResize
```
）
必填星号样式

How-To: Autofill, Highlight, and Icons

操作指南：自动填充、高亮与图标

📄 Read: references/how-to.md

```
autofill
```
– suggest first matched item on Arrow Down
```
highlight
```
– highlight typed characters in suggestion list
Icon support with
```
fields.iconCss
```

📄 阅读： references/how-to.md

```
autofill
```
– 按下向下箭头时建议第一个匹配项
```
highlight
```
– 在建议列表中高亮输入的字符
使用
```
fields.iconCss
```
支持图标

API Reference

API参考

📄 Read: references/api.md

All properties with types, defaults, and descriptions
All methods with parameters and return types
All events with descriptions

📄 阅读： references/api.md

所有属性的类型、默认值与描述
所有方法的参数与返回类型
所有事件的描述

Quick Start Example

快速入门示例

Installation: Pin packages to a specific major version to reduce supply-chain risk.
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-react-inputs@^33.x.x @syncfusion/ej2-base@^33.x.x

tsx

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-inputs/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

const sportsData: string[] = [
  'Badminton', 'Basketball', 'Cricket', 'Football',
  'Golf', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
];

export default function App() {
  return (
    <AutoCompleteComponent
      id="sports-ac"
      dataSource={sportsData}
      placeholder="Find a game"
    />
  );
}

安装： 将包固定到特定主版本以降低供应链风险。
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-react-inputs@^33.x.x @syncfusion/ej2-base@^33.x.x

tsx

import { AutoCompleteComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-inputs/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

const sportsData: string[] = [
  'Badminton', 'Basketball', 'Cricket', 'Football',
  'Golf', 'Hockey', 'Rugby', 'Snooker', 'Tennis'
];

export default function App() {
  return (
    <AutoCompleteComponent
      id="sports-ac"
      dataSource={sportsData}
      placeholder="Find a game"
    />
  );
}

Common Patterns

常见模式

Object data source with field mapping

带字段映射的对象数据源

tsx

const sportsData = [
  { id: 'Game1', game: 'Badminton' },
  { id: 'Game2', game: 'Basketball' },
];
const fields = { value: 'game' };

<AutoCompleteComponent dataSource={sportsData} fields={fields} placeholder="Find a game" />

tsx

const sportsData = [
  { id: 'Game1', game: 'Badminton' },
  { id: 'Game2', game: 'Basketball' },
];
const fields = { value: 'game' };

<AutoCompleteComponent dataSource={sportsData} fields={fields} placeholder="Find a game" />

Remote data binding (security-first)

远程数据绑定（安全优先）

Security: Do not call arbitrary third-party URLs directly from client code. Route external API calls through a trusted server-side proxy that enforces allowed endpoints, authentication, rate limits, and response validation.

tsx

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

// Use a controlled server proxy endpoint here. Do not use public third-party URLs directly.
const customerData = new DataManager({
  adaptor: new ODataV4Adaptor(),
  crossDomain: true,
  url: 'https://your-trusted-proxy.example/api/customers'
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { value: 'ContactName' };

<AutoCompleteComponent
  dataSource={customerData}
  query={query}
  fields={fields}
  sortOrder="Ascending"
  placeholder="Find a customer" />

安全提示： 不要直接从客户端代码调用任意第三方URL。通过受信任的服务器端代理路由外部API调用，该代理应强制执行允许的端点、身份验证、速率限制和响应验证。

tsx

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

// 此处使用受控服务器代理端点。不要直接使用公共第三方URL。
const customerData = new DataManager({
  adaptor: new ODataV4Adaptor(),
  crossDomain: true,
  url: 'https://your-trusted-proxy.example/api/customers'
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { value: 'ContactName' };

<AutoCompleteComponent
  dataSource={customerData}
  query={query}
  fields={fields}
  sortOrder="Ascending"
  placeholder="Find a customer" />

Filtering with custom options

带自定义选项的筛选

tsx

<AutoCompleteComponent
  dataSource={sportsData}
  filterType="StartsWith"
  minLength={2}
  suggestionCount={5}
  debounceDelay={300}
  ignoreCase={true}
  placeholder="Type to search"
/>

tsx

<AutoCompleteComponent
  dataSource={sportsData}
  filterType="StartsWith"
  minLength={2}
  suggestionCount={5}
  debounceDelay={300}
  ignoreCase={true}
  placeholder="Type to search"
/>

Accessing methods via ref

通过ref访问方法

tsx

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

export default function App() {
  const acRef = useRef<AutoCompleteComponent>(null);

  return (
    <>
      <AutoCompleteComponent ref={acRef} dataSource={sportsData} placeholder="Find a game" />
      <button onClick={() => acRef.current?.showPopup()}>Open</button>
      <button onClick={() => acRef.current?.clear()}>Clear</button>
    </>
  );
}

tsx

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

export default function App() {
  const acRef = useRef<AutoCompleteComponent>(null);

  return (
    <>
      <AutoCompleteComponent ref={acRef} dataSource={sportsData} placeholder="Find a game" />
      <button onClick={() => acRef.current?.showPopup()}>Open</button>
      <button onClick={() => acRef.current?.clear()}>Clear</button>
    </>
  );
}

ComboBox

ComboBox组件

The ComboBox component provides a dropdown input that allows users to type to filter or select from a predefined list. It supports local and remote data binding, custom values, filtering, grouping, templates, virtual scrolling, and full accessibility.

ComboBox组件提供了一个下拉输入框，允许用户通过输入进行筛选或从预定义列表中选择。它支持本地和远程数据绑定、自定义值、筛选、分组、模板、虚拟滚动以及完整的无障碍功能。

Component Overview

组件概述

The ComboBox is a specialized dropdown input that bridges typed input fields with selection lists. Key characteristics:

Hybrid input: User can type to filter OR select from dropdown
Smart filtering: Default filter searches by text, customizable for complex scenarios
Flexible data: Supports strings, JSON objects, OData, Web APIs, DataManager
Rich UI: Templates for items, headers, footers, selected values, no-results states
Performance: Virtual scrolling efficiently handles thousands of items
Global ready: Built-in localization, RTL support, ARIA attributes
Accessible: Full keyboard navigation, screen reader support

Installation: Pin packages to a specific major version to reduce supply-chain risk.
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x

ComboBox是一个专门的下拉输入框，它将输入字段与选择列表结合起来。主要特点：

混合输入： 用户可以输入内容进行筛选，也可以从下拉列表中选择
智能筛选： 默认筛选按文本搜索，可针对复杂场景进行自定义
灵活的数据支持： 支持字符串、JSON对象、OData、Web API、DataManager
丰富的UI： 项、头部、底部、选中值、无结果状态的模板
高性能： 虚拟滚动可高效处理数千条数据
全球化支持： 内置本地化、RTL支持、ARIA属性
无障碍： 完整的键盘导航、屏幕阅读器支持

安装： 将包固定到特定主版本以降低供应链风险。
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x

Documentation Navigation Guide

文档导航指南

Choose your starting point based on your task:

根据你的任务选择起点：

Getting Started

快速入门

📄 Read: references/getting-started.md

When to read:

Setting up ComboBox in a new project
First-time component implementation
Understanding basic usage (class vs functional components)
Adding CSS imports and themes
Enabling custom values

📄 阅读： references/getting-started.md

适用场景：

在新项目中设置ComboBox
首次实现组件
了解基本用法（类组件vs函数式组件）
添加CSS导入与主题
启用自定义值

Data Binding & Sources

数据绑定与数据源

📄 Read: references/data-binding.md

When to read:

Binding local data (string arrays, JSON objects)
Connecting to remote APIs (OData, Web API, DataManager)
Mapping object fields (text, value, groupBy, iconCss)
Handling complex data transformations
Understanding data source configuration

📄 阅读： references/data-binding.md

适用场景：

绑定本地数据（字符串数组、JSON对象）
连接到远程API（OData、Web API、DataManager）
映射对象字段（text、value、groupBy、iconCss）
处理复杂数据转换
了解数据源配置

Filtering & Search Behavior

筛选与搜索行为

📄 Read: references/filtering-and-search.md

When to read:

Implementing text filtering
Creating custom filter functions
Configuring search behavior (case sensitivity, partial matching)
Performance optimization for large datasets
Handling no-results scenarios

📄 阅读： references/filtering-and-search.md

适用场景：

实现文本筛选
创建自定义筛选函数
配置搜索行为（大小写敏感、部分匹配）
大型数据集的性能优化
处理无结果场景

Grouping & Sorting

分组与排序

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

When to read:

Organizing items into logical groups
Customizing group header appearance
Applying sort orders (ascending/descending)
Combining grouping with filtering
Multi-level grouping scenarios

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

适用场景：

将项组织为逻辑组
自定义分组标题外观
应用排序顺序（升序/降序）
结合分组与筛选
多级分组场景

Templates & Customization

模板与自定义

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

When to read:

Creating custom item templates
Displaying rich content (images, icons, descriptions)
Header/footer templates (e.g., action buttons, summaries)
Selected value template formatting
CSS class-based styling and theme customization

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

适用场景：

创建自定义项模板
显示丰富内容（图片、图标、描述）
头部/底部模板（如操作按钮、摘要）
选中值模板格式化
基于CSS类的样式与主题自定义

Advanced Features

高级功能

📄 Read: references/advanced-features.md

When to read:

Virtual scrolling for large datasets (10,000+ items)
Internationalization (i18n) and language switching
RTL (right-to-left) support for Arabic/Hebrew
Accessibility compliance (WCAG 2.1, ARIA attributes)
Disabled states and multi-select workflows
Keyboard shortcuts and focus management

📄 阅读： references/advanced-features.md

适用场景：

大型数据集的虚拟滚动（10,000+条数据）
国际化（i18n）与语言切换
阿拉伯语/希伯来语的RTL（从右到左）支持
无障碍合规性（WCAG 2.1、ARIA属性）
禁用状态与多选工作流
键盘快捷键与焦点管理

Styling & Theming

样式与主题

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

When to read:

Applying built-in Syncfusion themes (Material, Bootstrap, Tailwind)
CSS variable customization for brand colors
Theme Studio integration for design customization
Responsive design patterns
Dark mode / light mode support

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

适用场景：

应用内置Syncfusion主题（Material、Bootstrap、Tailwind）
自定义CSS变量以匹配品牌颜色
Theme Studio集成以进行设计自定义
响应式设计模式
深色/浅色模式支持

Popup Resizing

弹窗调整大小

📄 Read: references/popup-resizing.md

When to read:

Allowing users to dynamically resize the dropdown
Saving resize preferences across sessions
Handling long content with custom templates
Mobile-friendly dropdown sizing

📄 阅读： references/popup-resizing.md

适用场景：

允许用户动态调整下拉框大小
在会话间保存调整大小的偏好
使用自定义模板处理长内容
移动端友好的下拉框尺寸

How-To Guide

操作指南

📄 Read: references/how-to-guide.md

When to read:

Implementing autofill (auto-complete while typing)
Creating cascading/dependent dropdowns (Country → State → City)
Displaying icons in list items
Common practical implementation scenarios

📄 阅读： references/how-to-guide.md

适用场景：

实现自动填充（输入时自动完成）
创建级联/依赖下拉框（国家→州→城市）
在列表项中显示图标
常见的实际实现场景

Troubleshooting

故障排除

📄 Read: references/troubleshooting.md

When to read:

Performance issues (slow rendering, lag)
Data binding problems
Migration from EJ1 ComboBox
Common edge cases and workarounds
Debugging tips and community resources

📄 阅读： references/troubleshooting.md

适用场景：

性能问题（渲染缓慢、延迟）
数据绑定问题
从EJ1 ComboBox迁移
常见边缘情况与解决方法
调试技巧与社区资源

API Reference

API参考

📄 Read: references/api.md

When to read:

Looking up a specific property, method, or event name and its type
Understanding default values for any configuration option
Checking event argument shapes (
```
ChangeEventArgs
```
,
```
FilteringEventArgs
```
, etc.)
Reviewing all available methods for programmatic control
Exploring interface models (
```
FieldSettingsModel
```
,
```
PopupEventArgs
```
, etc.)

📄 阅读： references/api.md

适用场景：

查询特定属性、方法或事件名称及其类型
了解任何配置选项的默认值
检查事件参数的结构（
```
ChangeEventArgs
```
、
```
FilteringEventArgs
```
等）
查看所有可用的程序化控制方法
探索接口模型（
```
FieldSettingsModel
```
、
```
PopupEventArgs
```
等）

Quick Start Example

快速入门示例

Installation & Setup

安装与设置

Installation: Pin packages to a specific major version to reduce supply-chain risk.
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x

安装： 将包固定到特定主版本以降低供应链风险。
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x

Basic ComboBox (Functional Component)

基础ComboBox（函数式组件）

tsx

import { ComboBoxComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

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

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsList}
      placeholder="Select a sport"
      allowCustom={true}
    />
  );
}

tsx

import { ComboBoxComponent } from '@syncfusion/ej2-react-dropdowns';
import '@syncfusion/ej2-base/styles/tailwind3.css';
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';

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

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsList}
      placeholder="Select a sport"
      allowCustom={true}
    />
  );
}

With Data Binding (JSON Objects)

带数据绑定（JSON对象）

tsx

export default function App() {
  const sportsData = [
    { Id: 'game1', Game: 'Badminton', Players: 2 },
    { Id: 'game2', Game: 'Football', Players: 11 },
    { Id: 'game3', Game: 'Cricket', Players: 11 }
  ];

  const fields = { text: 'Game', value: 'Id' };

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
      change={(e) => console.log('Selected:', e.value)}
    />
  );
}

tsx

export default function App() {
  const sportsData = [
    { Id: 'game1', Game: 'Badminton', Players: 2 },
    { Id: 'game2', Game: 'Football', Players: 11 },
    { Id: 'game3', Game: 'Cricket', Players: 11 }
  ];

  const fields = { text: 'Game', value: 'Id' };

  return (
    <ComboBoxComponent 
      id="combobox"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
      change={(e) => console.log('Selected:', e.value)}
    />
  );
}

Common Patterns

常见模式

Pattern 1: Filtered Search for User Selection

模式1：用于用户选择的筛选搜索

Problem: User needs to find items in a list of 500+ entries.
Solution: Use filtering with controlled input to display only matching items. For very large datasets (5,000+ items), combine with

enableVirtualization

and inject

VirtualScroll

tsx

import { ComboBoxComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';

const [filterValue, setFilterValue] = useState('');

<ComboBoxComponent 
  dataSource={largeDataset}
  fields={{ text: 'name', value: 'id' }}
  filtering={(e) => filterByName(e, 'name')}
  change={(e) => setFilterValue(e.value)}
  allowFiltering={true}
  enableVirtualization={true}
  popupHeight="200px"
>
  <Inject services={[VirtualScroll]} />
</ComboBoxComponent>

问题： 用户需要在500+条条目的列表中查找项。
解决方案： 使用带受控输入的筛选来仅显示匹配项。对于非常大的数据集（5,000+条数据），结合

enableVirtualization

并注入

VirtualScroll

。

tsx

import { ComboBoxComponent, Inject, VirtualScroll } from '@syncfusion/ej2-react-dropdowns';

const [filterValue, setFilterValue] = useState('');

<ComboBoxComponent 
  dataSource={largeDataset}
  fields={{ text: 'name', value: 'id' }}
  filtering={(e) => filterByName(e, 'name')}
  change={(e) => setFilterValue(e.value)}
  allowFiltering={true}
  enableVirtualization={true}
  popupHeight="200px"
>
  <Inject services={[VirtualScroll]} />
</ComboBoxComponent>

Pattern 2: Grouped Categories

模式2：分组类别

Problem: Items need to be organized by type for clarity.
Solution: Use groupBy field mapping with data grouped by category.

tsx

const categorizedData = [
  { Category: 'Sports', Item: 'Cricket', value: 1 },
  { Category: 'Sports', Item: 'Football', value: 2 },
  { Category: 'Games', Item: 'Chess', value: 3 },
  { Category: 'Games', Item: 'Carrom', value: 4 }
];

const fields = { 
  text: 'Item', 
  value: 'value', 
  groupBy: 'Category' 
};

<ComboBoxComponent dataSource={categorizedData} fields={fields} />

问题： 需要按类型组织项以提高清晰度。
解决方案： 使用groupBy字段映射按类别分组的数据。

tsx

const categorizedData = [
  { Category: 'Sports', Item: 'Cricket', value: 1 },
  { Category: 'Sports', Item: 'Football', value: 2 },
  { Category: 'Games', Item: 'Chess', value: 3 },
  { Category: 'Games', Item: 'Carrom', value: 4 }
];

const fields = { 
  text: 'Item', 
  value: 'value', 
  groupBy: 'Category' 
};

<ComboBoxComponent dataSource={categorizedData} fields={fields} />

Pattern 3: Remote Data with Loading (security-first)

模式3：带加载状态的远程数据（安全优先）

Problem: Fetch data from an API based on user search.

Security-first solution: Route external API requests through a trusted server-side proxy that validates and sanitizes responses. Do not embed third‑party URLs directly in client-side code.

tsx

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

// Use your server-side proxy here. The proxy should enforce allowed upstream hosts and
// sanitize responses before returning to the client.
const dataManager = new DataManager({
  url: 'https://your-trusted-proxy.example/api/search',
  adaptor: new WebApiAdaptor()
});

<ComboBoxComponent 
  dataSource={dataManager}
  fields={{ text: 'name', value: 'id' }}
  allowFiltering={true} />

问题： 根据用户搜索从API获取数据。

安全优先解决方案： 通过受信任的服务器端代理路由外部API请求，该代理应验证并清理响应。不要在客户端代码中直接嵌入第三方URL。

tsx

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

// 此处使用你的服务器端代理。代理应强制执行允许的上游主机，并在返回给客户端之前清理响应。
const dataManager = new DataManager({
  url: 'https://your-trusted-proxy.example/api/search',
  adaptor: new WebApiAdaptor()
});

<ComboBoxComponent 
  dataSource={dataManager}
  fields={{ text: 'name', value: 'id' }}
  allowFiltering={true} />

Pattern 4: Custom Template for Rich Content

模式4：用于丰富内容的自定义模板

Problem: Display icons or additional info with each item.
Solution: Use itemTemplate prop for custom HTML rendering.

tsx

const itemTemplate = (props) => {
  return (
    <div className="flex items-center gap-2">
      <span className={`icon icon-${props.value}`}></span>
      <span>{props.name}</span>
      <small className="text-gray-500">({props.players} players)</small>
    </div>
  );
};

<ComboBoxComponent 
  dataSource={sportsData}
  itemTemplate={itemTemplate}
  fields={{ text: 'name', value: 'id' }}
/>

问题： 在每个项中显示图标或附加信息。
解决方案： 使用itemTemplate属性进行自定义HTML渲染。

tsx

const itemTemplate = (props) => {
  return (
    <div className="flex items-center gap-2">
      <span className={`icon icon-${props.value}`}></span>
      <span>{props.name}</span>
      <small className="text-gray-500">({props.players} players)</small>
    </div>
  );
};

<ComboBoxComponent 
  dataSource={sportsData}
  itemTemplate={itemTemplate}
  fields={{ text: 'name', value: 'id' }}
/>

Key Props Reference

关键属性参考

Prop	Type	Description	Common Use
`dataSource`	Array\|DataManager	Data items to display	All use cases
`fields`	FieldSettingsModel	Map data fields (text, value, groupBy, iconCss, disabled)	Complex data
`placeholder`	string	Hint text when empty	UX guidance
`allowCustom`	boolean	Allow user to enter custom values not in the list. Default: `true`	Open-ended input
`allowFiltering`	boolean	Enable filter bar (search box) in the popup. Default: `false`	Search capability
`enableVirtualization`	boolean	Enable virtual scrolling for large datasets. Requires `<Inject services={[VirtualScroll]} />` . Default: `false`	Large datasets (5,000+ items)
`sortOrder`	SortOrder	`'None'` \| `'Ascending'` \| `'Descending'` . Default: `null`	Sorted lists
`popupHeight`	string\|number	Dropdown height (e.g., `'300px'` ). Default: `'300px'`	Layout control
`popupWidth`	string\|number	Dropdown width (e.g., `'100%'` ). Default: `'100%'`	Layout control
`enabled`	boolean	Enable/disable component. Default: `true`	Conditional rendering
`readonly`	boolean	Prevent user input. Default: `false`	View-only mode
`showClearButton`	boolean	Show clear (×) button. Default: `true`	Allow clearing selection
`change`	EmitType<ChangeEventArgs>	Fires when selection changes	Event handling
`filtering`	EmitType<FilteringEventArgs>	Fires when user types; use for custom filter logic	Advanced search
`itemTemplate`	Function\|string	Custom item HTML for each list item	Rich UI

属性	类型	描述	常见用途
`dataSource`	Array\|DataManager	要显示的数据项	所有使用场景
`fields`	FieldSettingsModel	映射数据字段（text、value、groupBy、iconCss、disabled）	复杂数据
`placeholder`	string	为空时的提示文本	用户体验引导
`allowCustom`	boolean	允许用户输入列表中不存在的自定义值。默认值： `true`	开放式输入
`allowFiltering`	boolean	在弹窗中启用筛选栏（搜索框）。默认值： `false`	搜索功能
`enableVirtualization`	boolean	为大型数据集启用虚拟滚动。需要 `<Inject services={[VirtualScroll]} />` 。默认值： `false`	大型数据集（5,000+条数据）
`sortOrder`	SortOrder	`'None'` \| `'Ascending'` \| `'Descending'` 。默认值： `null`	已排序列表
`popupHeight`	string\|number	下拉框高度（例如 `'300px'` ）。默认值： `'300px'`	布局控制
`popupWidth`	string\|number	下拉框宽度（例如 `'100%'` ）。默认值： `'100%'`	布局控制
`enabled`	boolean	启用/禁用组件。默认值： `true`	条件渲染
`readonly`	boolean	阻止用户输入。默认值： `false`	仅查看模式
`showClearButton`	boolean	显示清除（×）按钮。默认值： `true`	允许清除选择
`change`	EmitType<ChangeEventArgs>	选择更改时触发	事件处理
`filtering`	EmitType<FilteringEventArgs>	用户输入时触发；用于自定义筛选逻辑	高级搜索
`itemTemplate`	Function\|string	每个列表项的自定义HTML	丰富UI

Next Steps

下一步

New to ComboBox? → Start with getting-started.md
Need specific data? → Go to data-binding.md
Performance concerns? → Check advanced-features.md
Design customization? → See styling-and-theming.md
Common scenarios? → Explore how-to-guide.md (autofill, cascading, icons)
Resizable dropdowns? → Read popup-resizing.md
Stuck? → Visit troubleshooting.md
Need full API details? → See api.md for all properties, methods, events, and interface models

首次使用ComboBox？ → 从getting-started.md开始
需要特定数据？ → 前往data-binding.md
性能问题？ → 查看advanced-features.md
设计自定义？ → 参考styling-and-theming.md
常见场景？ → 探索how-to-guide.md（自动填充、级联、图标）
可调整大小的下拉框？ → 阅读popup-resizing.md
遇到问题？ → 访问troubleshooting.md
需要完整API详情？ → 查看api.md获取所有属性、方法、事件和接口模型

DropDownList

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适配器）
值绑定：预选值、绑定原始值vs复杂对象
通过
```
fields.disabled
```
禁用单个项

Filtering

筛选

📄 Read: references/filtering.md

Enabling
```
allowFiltering
```
for search-as-you-type
Handling the
```
filtering
```
event with
```
updateData
```
Preventing default filtering — always set
```
args.preventDefaultAction = true
```
in custom handlers
Filter types:
```
startswith
```
,
```
contains
```
,
```
endsWith
```
, case-sensitive options
Filtering by multiple fields — use
```
Predicate
```
with
```
.or()
```
to match typed text against both
```
text
```
and
```
value
```
fields (or any combination)
Remote/server-side filtering with minimum character guard
Diacritics filtering (
```
ignoreAccent
```
), debounce delay
Highlight filtered text, custom search logic

📄 阅读： references/filtering.md

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

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
cssClass
prop — scoped per-instance CSS class, multiple classes, conditional classes, built-in utility classes (
```
e-error
```
,
```
e-success
```
)
CSS class customization (wrapper, icon, popup, list items, placeholder)
Theming (tailwind3, material3, bootstrap5, fluent2)

Localization (

L10n

noRecordsTemplate

actionFailureTemplate

)

RTL layout (
```
enableRtl
```
)

📄 阅读： 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 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

属性、方法和事件的快速参考摘要表

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

快速入门示例

Installation: Pin packages to a specific major version to reduce supply-chain risk.
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x --save

tsx

// 1. See pinned install command above.

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

安装： 将包固定到特定主版本以降低供应链风险。
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x --save

tsx

// 1. 参见上面的固定版本安装命令。

// 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) {
    // Local example: updateData is applied against local `searchData` below.
    // For remote filtering, route requests through a trusted server proxy and
    // validate/sanitize responses before calling `updateData`.
    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"
    />
  );
}

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) {
    // 本地示例：updateData应用于下面的本地`searchData`。
    // 对于远程筛选，通过受信任的服务器代理路由请求，并在调用`updateData`之前验证/清理响应。
    args.preventDefaultAction = true; // 阻止内置筛选与自定义逻辑同时运行
    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

。

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

enableVirtualization

+ 注入

VirtualScroll

；阅读

references/features-and-configuration.md

。

依赖下拉框 → 在第一个下拉框的

change

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

dataSource

；阅读

references/how-to.md

。

ListBox

ListBox组件

The Syncfusion ListBox component displays a list of items in a scrollable container, enabling single or multiple selection. It supports local and remote data binding, drag-and-drop reordering, filtering, grouping, custom templates, dual-list transfer, and full accessibility.

Syncfusion ListBox组件在可滚动容器中显示项列表，支持单选或多选。它支持本地和远程数据绑定、拖放重新排序、筛选、分组、自定义模板、双列表传输以及完整的无障碍功能。

Documentation Guide

文档指南

Navigate to specific topics based on your implementation needs:

根据你的实现需求导航到特定主题：

Getting Started

快速入门

📄 Read: references/getting-started.md

React app setup (Vite/Create React App)
Installing Syncfusion packages
CSS imports and theming
Basic ListBox component creation
Running the application

📄 阅读： references/getting-started.md

React应用设置（Vite/Create React App）
安装Syncfusion包
CSS导入与主题设置
创建基础ListBox组件
运行应用

Selection & Events

选择与事件

📄 Read: references/selection.md

Single selection mode
Multiple selection mode
Selection events and handlers
Programmatic selection management
Working with selected items

📄 阅读： references/selection.md

单选模式
多选模式
选择事件与处理程序
程序化选择管理
处理选中项

Data Binding & Structure

数据绑定与结构

📄 Read: references/data-binding.md

Array and object data binding
Text and value properties
Data source configuration
Grouping data
Hierarchical data structures

📄 阅读： references/data-binding.md

数组和对象数据绑定
文本和值属性
数据源配置
数据分组
分层数据结构

Custom Templates & Icons

自定义模板与图标

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

Icon rendering in items
Custom item templates
HTML content rendering
Template variables and syntax
Conditional rendering

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

项中的图标渲染
自定义项模板
HTML内容渲染
模板变量与语法
条件渲染

Advanced Features

高级功能

📄 Read: references/features.md

Drag and drop functionality
Filtering and search
Sorting and grouping
Dual ListBox (transfer list)
Scroller configuration
Item enable/disable

📄 阅读： references/features.md

拖放功能
筛选与搜索
排序与分组
双ListBox（传输列表）
滚动器配置
项启用/禁用

Styling & Appearance

样式与外观

📄 Read: references/style-and-appearance.md

CSS class customization
Theme integration
Styling items and groups
Responsive design
Custom CSS variables

📄 阅读： references/style-and-appearance.md

CSS类自定义
主题集成
项和组的样式
响应式设计
自定义CSS变量

Accessibility

无障碍

📄 Read: references/accessibility.md

WCAG 2.2 compliance
Keyboard navigation
ARIA attributes
Screen reader support
RTL (right-to-left) support

📄 阅读： references/accessibility.md

WCAG 2.2合规性
键盘导航
ARIA属性
屏幕阅读器支持
RTL（从右到左）支持

How-To Guides

操作指南

📄 Read: references/how-to-guides.md

Add items dynamically
Select items programmatically
Enable/disable items
Filter ListBox data
Enable scroller for long lists
Form integration & submission

📄 阅读： references/how-to-guides.md

动态添加项
程序化选择项
启用/禁用项
筛选ListBox数据
为长列表启用滚动器
表单集成与提交

Dual ListBox (Transfer)

双ListBox（传输）

📄 Read: references/dual-list-box.md

Two-way item transfer between lists
Toolbar operations (move up/down, transfer)
Permission and skill assignment patterns
Custom styling and responsive design
Capacity limits and validation

📄 阅读： references/dual-list-box.md

列表间双向项传输
工具栏操作（上移/下移、传输）
权限和技能分配模式
自定义样式与响应式设计
容量限制与验证

API Reference

API参考

📄 Read: references/api.md

Complete list of all properties with types and defaults
All public methods with parameter details and return types
All events with full event argument interfaces

Sub-interfaces:

SelectionSettingsModel

ToolbarSettingsModel

FieldSettingsModel

SourceDestinationModel

📄 阅读： references/api.md

所有属性的完整列表，包含类型和默认值
所有公共方法的参数详情和返回类型
所有事件的完整事件参数接口

子接口：

SelectionSettingsModel

、

ToolbarSettingsModel

、

FieldSettingsModel

、

SourceDestinationModel

Quick Start Example

快速入门示例

Installation: Pin packages to a specific major version to reduce supply-chain risk.
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-base@^33.x.x

Basic ListBox with single selection:

tsx

import { ListBoxComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import './App.css';

function App() {
  const data = [
    { text: 'JavaScript', id: '1' },
    { text: 'TypeScript', id: '2' },
    { text: 'React', id: '3' },
    { text: 'Vue', id: '4' },
    { text: 'Angular', id: '5' }
  ];

  const handleChange = (e) => {
    console.log('Selected:', e.value);
  };

  return (
    <ListBoxComponent 
      dataSource={data}
      fields={{ text: 'text', value: 'id' }}
      selectionSettings={{ mode: 'Single' }}
      change={handleChange}
    />
  );
}

export default App;

安装： 将包固定到特定主版本以降低供应链风险。
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-base@^33.x.x

带单选的基础ListBox：

tsx

import { ListBoxComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import './App.css';

function App() {
  const data = [
    { text: 'JavaScript', id: '1' },
    { text: 'TypeScript', id: '2' },
    { text: 'React', id: '3' },
    { text: 'Vue', id: '4' },
    { text: 'Angular', id: '5' }
  ];

  const handleChange = (e) => {
    console.log('Selected:', e.value);
  };

  return (
    <ListBoxComponent 
      dataSource={data}
      fields={{ text: 'text', value: 'id' }}
      selectionSettings={{ mode: 'Single' }}
      change={handleChange}
    />
  );
}

export default App;

Common Patterns

常见模式

Multiple Selection

多选

tsx

<ListBoxComponent 
  dataSource={data}
  selectionSettings={{ mode: 'Multiple' }}
/>

tsx

<ListBoxComponent 
  dataSource={data}
  selectionSettings={{ mode: 'Multiple' }}
/>

Checkbox Selection

复选框选择

Requires injecting
CheckBoxSelection
service.

tsx

import { ListBoxComponent, SelectionSettingsModel, Inject, CheckBoxSelection } from '@syncfusion/ej2-react-dropdowns';

const selectionSettings: SelectionSettingsModel = { showCheckbox: true };

<ListBoxComponent dataSource={data} selectionSettings={selectionSettings}>
  <Inject services={[CheckBoxSelection]} />
</ListBoxComponent>

需要注入
CheckBoxSelection
服务。

tsx

import { ListBoxComponent, SelectionSettingsModel, Inject, CheckBoxSelection } from '@syncfusion/ej2-react-dropdowns';

const selectionSettings: SelectionSettingsModel = { showCheckbox: true };

<ListBoxComponent dataSource={data} selectionSettings={selectionSettings}>
  <Inject services={[CheckBoxSelection]} />
</ListBoxComponent>

With Search/Filter

带搜索/筛选

tsx

<ListBoxComponent 
  dataSource={data}
  allowFiltering={true}
  filterBarPlaceholder="Search items"
/>

tsx

<ListBoxComponent 
  dataSource={data}
  allowFiltering={true}
  filterBarPlaceholder="Search items"
/>

Custom Item Template

自定义项模板

tsx

const itemTemplate = (props) => {
  return (
    <div>
      <span className="icon">{props.icon}</span>
      <span>{props.text}</span>
    </div>
  );
}

<ListBoxComponent 
  dataSource={data}
  itemTemplate={itemTemplate}
/>

tsx

const itemTemplate = (props) => {
  return (
    <div>
      <span className="icon">{props.icon}</span>
      <span>{props.text}</span>
    </div>
  );
}

<ListBoxComponent 
  dataSource={data}
  itemTemplate={itemTemplate}
/>

Grouping Items

分组项

tsx

<ListBoxComponent 
  dataSource={groupedData}
  fields={{ text: 'text', groupBy: 'category' }}
/>

tsx

<ListBoxComponent 
  dataSource={groupedData}
  fields={{ text: 'text', groupBy: 'category' }}
/>

Key Props & Configuration

关键属性与配置

Prop	Purpose	Example
`dataSource`	Array of items to display	`[{ text: 'Item', id: '1' }]`
`fields`	Maps data properties to display	`{ text: 'name', value: 'id' }`
`selectionSettings`	Defines selection mode and checkbox display. For `showCheckbox: true` , inject `CheckBoxSelection` service	`{ mode: 'Multiple' }` / `{ showCheckbox: true }`
`allowFiltering`	Enables filter search box	`true`
`allowDragAndDrop`	Enables item drag-drop	`true`
`itemTemplate`	Custom template for items	Function returning JSX
`enabled`	Enables/disables the component	`true` / `false`

属性	用途	示例
`dataSource`	要显示的项数组	`[{ text: 'Item', id: '1' }]`
`fields`	映射数据属性以显示	`{ text: 'name', value: 'id' }`
`selectionSettings`	定义选择模式和复选框显示。对于 `showCheckbox: true` ，需注入 `CheckBoxSelection` 服务	`{ mode: 'Multiple' }` / `{ showCheckbox: true }`
`allowFiltering`	启用筛选搜索框	`true`
`allowDragAndDrop`	启用项拖放	`true`
`itemTemplate`	项的自定义模板	返回JSX的函数
`enabled`	启用/禁用组件	`true` / `false`

Common Use Cases

常见使用场景

Select Framework - Single selection from framework list with icons
Multi-Select Languages - Multiple selection with search filter
Skill Picker - Custom templates with badges and descriptions
Drag-Drop Transfer - Dual ListBox for moving items between lists
Grouped Categories - Organizing items by category with group headers
Searchable Item List - Large list with filter functionality
Accessible Menu - Full keyboard navigation and screen reader support

选择框架 - 带图标的框架列表单选
多选语言 - 带搜索筛选的多选
技能选择器 - 带徽章和描述的自定义模板
拖放传输 - 用于在列表间移动项的双ListBox
分组类别 - 按类别组织项并显示分组标题
可搜索项列表 - 带筛选功能的大型列表
无障碍菜单 - 完整的键盘导航和屏幕阅读器支持

Next Steps

下一步

Start with Getting Started for initial setup
Choose your use case (selection mode, templates, features)
Read relevant reference for implementation details
Copy code examples and customize for your needs
Use Accessibility guide for WCAG compliance

Need help? Each reference file contains examples, edge cases, and troubleshooting tips.

从快速入门开始进行初始设置
选择你的使用场景（选择模式、模板、功能）
阅读相关参考获取实现细节
复制代码示例并根据需求自定义
使用无障碍指南确保WCAG合规

需要帮助？ 每个参考文件都包含示例、边缘情况和故障排除提示。

Mention

Mention组件

The Mention Component attaches to a target editable element (e.g. a

<div contenteditable>

) and displays a suggestion popup when the user types a trigger character (default

). Selecting an item inserts it inline into the editor.

Mention组件附加到目标可编辑元素（例如

<div contenteditable>

），当用户输入触发字符（默认

）时显示建议弹窗。选择项后会将其插入到编辑器中。

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup (
```
@syncfusion/ej2-react-dropdowns
```
)
CSS theme imports
Basic
```
MentionComponent
```
setup with
```
target
```
prop
Binding a simple data source
Custom trigger character (
```
mentionChar
```
) and
```
showMentionChar
```

⚠️ Security Note: Installing npm packages (
@syncfusion/ej2-react-dropdowns
and related) must be a deliberate, user-confirmed step. Do not allow automated agents to run
npm install
without explicit user approval, as this introduces supply-chain risk.

📄 阅读： references/getting-started.md

安装与包设置（
```
@syncfusion/ej2-react-dropdowns
```
）
CSS主题导入
带
```
target
```
属性的基础
```
MentionComponent
```
设置
绑定简单数据源
自定义触发字符（
```
mentionChar
```
）和
```
showMentionChar
```

⚠️ 安全注意： 安装npm包（
@syncfusion/ej2-react-dropdowns
及相关包）必须是用户确认的 deliberate操作。不要允许自动化代理在未经用户明确批准的情况下运行
npm install
，因为这会带来供应链风险。

Working with Data

数据处理

📄 Read: references/working-with-data.md

Binding array of strings, JSON objects, and complex nested data
Mapping
```
fields
```
(text, value, groupBy, iconCss)
Remote data with OData V4 (
```
ODataV4Adaptor
```
)
Remote data with Web API (
```
WebApiAdaptor
```
)
Using
```
query
```
to filter/select remote fields

📄 阅读： references/working-with-data.md

绑定字符串数组、JSON对象和复杂嵌套数据
映射
```
fields
```
（text、value、groupBy、iconCss）
使用OData V4的远程数据（
```
ODataV4Adaptor
```
）
使用Web API的远程数据（
```
WebApiAdaptor
```
）
使用
```
query
```
筛选/选择远程字段

Filtering Data

数据筛选

📄 Read: references/filtering-data.md

Setting minimum filter character length (
```
minLength
```
)
Changing filter type:
```
Contains
```
,
```
StartsWith
```
,
```
EndsWith
```
Allowing spaces within search text (
```
allowSpaces
```
)
Customizing the suggestion count (
```
suggestionCount
```
)
Debounce delay for filtering (
```
debounceDelay
```
)

📄 阅读： references/filtering-data.md

设置最小筛选字符长度（
```
minLength
```
）
更改筛选类型：
```
Contains
```
、
```
StartsWith
```
、
```
EndsWith
```
允许搜索文本中包含空格（
```
allowSpaces
```
）
自定义建议数量（
```
suggestionCount
```
）
筛选的防抖延迟（
```
debounceDelay
```
）

Templates

模板

📄 Read: references/template.md

Item template (
```
itemTemplate
```
) for custom list rendering
Display template (
```
displayTemplate
```
) for selected value format
No-records template (
```
noRecordsTemplate
```
)
Spinner/loading template (
```
spinnerTemplate
```
)
Group header template (
```
groupTemplate
```
)

📄 阅读： references/template.md

用于自定义列表渲染的项模板（
```
itemTemplate
```
）
用于选中值格式的显示模板（
```
displayTemplate
```
）
无记录模板（
```
noRecordsTemplate
```
）
加载中/ spinner模板（
```
spinnerTemplate
```
）
分组标题模板（
```
groupTemplate
```
）

Customization

自定义

📄 Read: references/customization.md

Show/hide mention character in output (
```
showMentionChar
```
)
Appending suffix text after selection (
```
suffixText
```
)
Configuring popup height and width (
```
popupHeight
```
,
```
popupWidth
```
)
Custom trigger character (
```
mentionChar
```
)
Leading space requirement (
```
requireLeadingSpace
```
)
CSS class customization (
```
cssClass
```
)
Highlight matched characters (
```
highlight
```
)
Ignore accent/case in search (
```
ignoreAccent
```
,
```
ignoreCase
```
)
Z-index for popup (
```
zIndex
```
)

📄 阅读： references/customization.md

在输出中显示/隐藏提及字符（
```
showMentionChar
```
）
选择后附加后缀文本（
```
suffixText
```
）
配置弹窗高度和宽度（
```
popupHeight
```
、
```
popupWidth
```
）
自定义触发字符（
```
mentionChar
```
）
前置空格要求（
```
requireLeadingSpace
```
）
CSS类自定义（
```
cssClass
```
）
高亮匹配字符（
```
highlight
```
）
搜索时忽略重音/大小写（
```
ignoreAccent
```
、
```
ignoreCase
```
）
弹窗的Z-index（
```
zIndex
```
）

Sorting

排序

📄 Read: references/sorting.md

Sorting suggestion list:
```
Ascending
```
,
```
Descending
```
,
```
None
```

📄 阅读： references/sorting.md

建议列表排序：
```
Ascending
```
、
```
Descending
```
、
```
None
```

Disabled Items

禁用项

📄 Read: references/disabled-items.md

Disabling items via
```
fields.disabled
```
Dynamically disabling items with
```
disableItem()
```
method

📄 阅读： references/disabled-items.md

通过
```
fields.disabled
```
禁用项
使用
```
disableItem()
```
方法动态禁用项

Accessibility

无障碍

📄 Read: references/accessibility.md

WAI-ARIA attributes (

aria-selected

aria-activedescendent

aria-owns

)

Keyboard navigation shortcuts
WCAG 2.2 and Section 508 compliance
RTL support (
```
enableRtl
```
)

📄 阅读： references/accessibility.md

WAI-ARIA属性（

aria-selected

、

aria-activedescendent

、

aria-owns

）

键盘导航快捷键
WCAG 2.2和Section 508合规性
RTL支持（
```
enableRtl
```
）

Localization

本地化

📄 Read: references/localization.md

Localizing the
```
noRecordsTemplate
```
text via
```
L10n
```
Setting
```
locale
```
property

📄 阅读： references/localization.md

通过
```
L10n
```
本地化
```
noRecordsTemplate
```
文本
设置
```
locale
```
属性

API Reference

API参考

📄 Read: references/api.md

All properties, methods, and events

target

dataSource

fields

mentionChar

minLength

suggestionCount

Methods:

addItem

disableItem

getDataByValue

getItems

showPopup

hidePopup

search

destroy

Events:

select

change

filtering

beforeOpen

opened

closed

dataBound

actionBegin

actionComplete

actionFailure

📄 阅读： references/api.md

所有属性、方法和事件

target

、

dataSource

、

fields

、

mentionChar

、

minLength

、

suggestionCount

方法：

addItem

、

disableItem

、

getDataByValue

、

getItems

、

showPopup

、

hidePopup

、

search

、

destroy

事件：

select

、

change

、

filtering

、

beforeOpen

、

opened

、

closed

、

dataBound

、

actionBegin

、

actionComplete

、

actionFailure

Quick Start Example

快速入门示例

tsx

import { MentionComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

// CSS imports
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

function App() {
  const mentionTarget = '#commentBox';
  const users = [
    { Name: 'Selma Rose', EmailId: 'selma@example.com' },
    { Name: 'Robert', EmailId: 'robert@example.com' },
    { Name: 'William', EmailId: 'william@example.com' },
  ];
  const fields = { text: 'Name' };

  return (
    <div>
      <label>Comments</label>
      <div id="commentBox" placeholder="Type @ to mention a user"></div>
      <MentionComponent
        target={mentionTarget}
        dataSource={users}
        fields={fields}
      />
    </div>
  );
}

export default App;

tsx

import { MentionComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

// CSS导入
// @import "../node_modules/@syncfusion/ej2-base/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-dropdowns/styles/tailwind3.css";

function App() {
  const mentionTarget = '#commentBox';
  const users = [
    { Name: 'Selma Rose', EmailId: 'selma@example.com' },
    { Name: 'Robert', EmailId: 'robert@example.com' },
    { Name: 'William', EmailId: 'william@example.com' },
  ];
  const fields = { text: 'Name' };

  return (
    <div>
      <label>Comments</label>
      <div id="commentBox" placeholder="Type @ to mention a user"></div>
      <MentionComponent
        target={mentionTarget}
        dataSource={users}
        fields={fields}
      />
    </div>
  );
}

export default App;

Common Patterns

常见模式

Custom Trigger Character

自定义触发字符

Use

mentionChar

to trigger with

instead of

tsx

<MentionComponent
  target="#editor"
  dataSource={tags}
  mentionChar="#"
  showMentionChar={true}
/>

使用

mentionChar

将触发字符改为

而非

：

tsx

<MentionComponent
  target="#editor"
  dataSource={tags}
  mentionChar="#"
  showMentionChar={true}
/>

Remote Data with Filtering (security-first)

带筛选的远程数据（安全优先）

tsx

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

// SECURITY: Do not call third-party endpoints from the browser. Use a server-side
// proxy that you control and that validates/sanitizes upstream responses.
const dataSource = new DataManager({
  url: 'https://your-trusted-proxy.example/api/mentions',
  adaptor: new ODataV4Adaptor(),
  crossDomain: true,
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { text: 'ContactName', value: 'CustomerID' };

<MentionComponent
  target="#editor"
  dataSource={dataSource}
  fields={fields}
  query={query}
  minLength={2}
  popupWidth="250px" />

tsx

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

// 安全提示：不要从浏览器调用第三方端点。使用你控制的服务器端代理，该代理应验证/清理上游响应。
const dataSource = new DataManager({
  url: 'https://your-trusted-proxy.example/api/mentions',
  adaptor: new ODataV4Adaptor(),
  crossDomain: true,
});
const query = new Query().from('Customers').select(['ContactName', 'CustomerID']).take(6);
const fields = { text: 'ContactName', value: 'CustomerID' };

<MentionComponent
  target="#editor"
  dataSource={dataSource}
  fields={fields}
  query={query}
  minLength={2}
  popupWidth="250px" />

Handling Selection Events

处理选择事件

tsx

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

function onSelect(args: SelectEventArgs) {
  console.log('Selected item:', args.itemData);
  console.log('Selected text:', args.text);
}

<MentionComponent
  target="#editor"
  dataSource={users}
  fields={{ text: 'Name' }}
  select={onSelect}
/>

tsx

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

function onSelect(args: SelectEventArgs) {
  console.log('Selected item:', args.itemData);
  console.log('Selected text:', args.text);
}

<MentionComponent
  target="#editor"
  dataSource={users}
  fields={{ text: 'Name' }}
  select={onSelect}
/>

Popup Configuration

弹窗配置

tsx

<MentionComponent
  target="#editor"
  dataSource={data}
  fields={{ text: 'Name' }}
  popupHeight="200px"
  popupWidth="300px"
  suggestionCount={10}
  sortOrder="Ascending"
  suffixText="&nbsp;"
/>

tsx

<MentionComponent
  target="#editor"
  dataSource={data}
  fields={{ text: 'Name' }}
  popupHeight="200px"
  popupWidth="300px"
  suggestionCount={10}
  sortOrder="Ascending"
  suffixText="&nbsp;"
/>

Key Props Summary

关键属性摘要

Prop	Type	Default	Purpose
`target`	`string\|HTMLElement`	—	CSS selector or element for the editable area
`dataSource`	`array\|DataManager`	`[]`	Data for suggestions
`fields`	`FieldSettingsModel`	`{text:null,value:null}`	Maps data fields
`mentionChar`	`string`	`'@'`	Trigger character
`showMentionChar`	`boolean`	`false`	Prepend trigger char to inserted text
`minLength`	`number`	`0`	Min chars before search
`suggestionCount`	`number`	`25`	Max items in popup
`filterType`	`FilterType`	`'Contains'`	Filter match strategy
`allowSpaces`	`boolean`	`false`	Allow spaces in search
`sortOrder`	`SortOrder`	`'None'`	Sort direction
`popupHeight`	`string\|number`	`'300px'`	Popup height
`popupWidth`	`string\|number`	`'auto'`	Popup width
`suffixText`	`string`	`null`	Text appended after selection
`requireLeadingSpace`	`boolean`	`true`	Space required before trigger char
`highlight`	`boolean`	`false`	Highlight search characters

属性	类型	默认值	用途
`target`	`string\|HTMLElement`	—	可编辑区域的CSS选择器或元素
`dataSource`	`array\|DataManager`	`[]`	建议数据
`fields`	`FieldSettingsModel`	`{text:null,value:null}`	映射数据字段
`mentionChar`	`string`	`'@'`	触发字符
`showMentionChar`	`boolean`	`false`	在插入的文本前添加触发字符
`minLength`	`number`	`0`	触发搜索的最小字符数
`suggestionCount`	`number`	`25`	弹窗中的最大项数
`filterType`	`FilterType`	`'Contains'`	筛选匹配策略
`allowSpaces`	`boolean`	`false`	允许搜索文本中包含空格
`sortOrder`	`SortOrder`	`'None'`	排序方向
`popupHeight`	`string\|number`	`'300px'`	弹窗高度
`popupWidth`	`string\|number`	`'auto'`	弹窗宽度
`suffixText`	`string`	`null`	选择后附加的文本
`requireLeadingSpace`	`boolean`	`true`	触发字符前需要空格
`highlight`	`boolean`	`false`	高亮搜索字符

MultiSelect

MultiSelect组件

A comprehensive skill for implementing the MultiSelect Dropdown component — enabling users to select multiple values from a list with support for filtering, grouping, templates, checkboxes, chips, virtual scrolling, and more.

这是一份关于实现MultiSelect下拉组件的全面指南——支持用户从列表中选择多个值，具备筛选、分组、模板、复选框、标签、虚拟滚动等功能。

Component Overview

组件概述

Installation: Pin packages to a specific major version to reduce supply-chain risk.
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-base@^33.x.x @syncfusion/ej2-buttons@^33.x.x @syncfusion/ej2-inputs@^33.x.x

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';
// Also import base dependencies:
// @syncfusion/ej2-base/styles/tailwind3.css
// @syncfusion/ej2-buttons/styles/tailwind3.css
// @syncfusion/ej2-inputs/styles/tailwind3.css

Package:

@syncfusion/ej2-react-dropdowns

Main component:

MultiSelectComponent

Checkbox module:

CheckBoxSelection

(inject via

<Inject services={[CheckBoxSelection]} />

)
Virtual scroll module:

VirtualScroll

(inject via

<Inject services={[VirtualScroll]} />

)

安装： 将包固定到特定主版本以降低供应链风险。
bash
npm install @syncfusion/ej2-react-dropdowns@^33.x.x @syncfusion/ej2-base@^33.x.x @syncfusion/ej2-buttons@^33.x.x @syncfusion/ej2-inputs@^33.x.x

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns'; // ^33.x.x
import '@syncfusion/ej2-react-dropdowns/styles/tailwind3.css';
// 同时导入基础依赖：
// @syncfusion/ej2-base/styles/tailwind3.css
// @syncfusion/ej2-buttons/styles/tailwind3.css
// @syncfusion/ej2-inputs/styles/tailwind3.css

包：

@syncfusion/ej2-react-dropdowns

主组件：

MultiSelectComponent

复选框模块：

CheckBoxSelection

（通过

<Inject services={[CheckBoxSelection]} />

注入）
虚拟滚动模块：

VirtualScroll

（通过

<Inject services={[VirtualScroll]} />

注入）

Quick Start Example

快速入门示例

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

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

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      placeholder="Select sports"
    />
  );
}

With objects and field mapping:

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const sportsData = [
    { id: 'game1', sports: 'Badminton' },
    { id: 'game2', sports: 'Football' },
    { id: 'game3', sports: 'Tennis' },
  ];
  const fields = { text: 'sports', value: 'id' };

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
    />
  );
}

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

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

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      placeholder="Select sports"
    />
  );
}

带对象和字段映射：

tsx

import { MultiSelectComponent } from '@syncfusion/ej2-react-dropdowns';
import * as React from 'react';

export default function App() {
  const sportsData = [
    { id: 'game1', sports: 'Badminton' },
    { id: 'game2', sports: 'Football' },
    { id: 'game3', sports: 'Tennis' },
  ];
  const fields = { text: 'sports', value: 'id' };

  return (
    <MultiSelectComponent
      id="multiselect"
      dataSource={sportsData}
      fields={fields}
      placeholder="Select a game"
    />
  );
}

Documentation and Navigation Guide

文档与导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup (Vite / CRA)
CSS imports and theming
Basic MultiSelect implementation (class & functional components)
Binding a simple data source
Popup height/width configuration

📄 阅读： references/getting-started.md

安装与包设置（Vite / CRA）
CSS导入与主题设置
基础MultiSelect实现（类组件&函数式组件）
绑定简单数据源
弹窗高度/宽度配置

Data Binding

数据绑定

📄 Read: references/data-binding.md

Array of strings vs array of objects
Field mapping (
```
text
```
,
```
value
```
,
```
groupBy
```
,
```
iconCss
```
,
```
disabled
```
)
Remote data via
```
DataManager
```
(OData, OData V4, Web API)
JSON/JSONP formats
Complex data binding gotchas

📄 阅读： references/data-binding.md

字符串数组vs对象数组
字段映射（
```
text
```
、
```
value
```
、
```
groupBy
```
、
```
iconCss
```
、
```
disabled
```
）
通过
```
DataManager
```
的远程数据（OData、OData V4、Web API）
JSON/JSONP格式
复杂数据绑定注意事项

Grouping

分组

📄 Read: references/grouping.md

Grouping items by category with
```
groupBy
```
Inline vs fixed group headers
Group header templates
Ordering and multi-level grouping

📄 阅读： references/grouping.md

使用
```
groupBy
```
按类别分组项
内联vs固定分组标题
分组标题模板
排序和多级分组

Filtering

筛选

📄 Read: references/filtering.md

Enabling
```
allowFiltering
```
Handling the
```
filtering
```
event
Query API with
```
where()
```
conditions
Filter types: startswith, contains, endswith
Case sensitivity, multiple conditions, performance

📄 阅读： references/filtering.md

启用
```
allowFiltering
```
处理
```
filtering
```
事件
带
```
where()
```
条件的Query API
筛选类型：startswith、contains、endswith
大小写敏感、多条件、性能

Templates

模板

📄 Read: references/templates.md

Item templates for custom list item layouts
Value/chip templates for selected display
Group header templates
Header, footer, no-records, and action-failure templates

📄 阅读： references/templates.md

用于自定义列表项布局的项模板
用于选中显示的值/标签模板
分组标题模板
头部、底部、无记录和操作失败模板

Selection Modes and Features

选择模式与功能

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

Checkbox mode (inject
```
CheckBoxSelection
```
)
Chip/tag display and the
```
tagging
```
event
Custom values (
```
allowCustomValue
```
)
Value binding (primitive and object types)
Disabled items via
```
fields.disabled
```
Popup resizing (
```
allowResize
```
)
Virtual scrolling for large datasets (inject
```
VirtualScroll
```
)

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

复选框模式（注入
```
CheckBoxSelection
```
）
标签/标记显示和
```
tagging
```
事件
自定义值（
```
allowCustomValue
```
）
值绑定（原始值和对象类型）
通过
```
fields.disabled
```
禁用项
弹窗调整大小（
```
allowResize
```
）
大型数据集的虚拟滚动（注入
```
VirtualScroll
```
）

Accessibility, Styling, and Localization

无障碍、样式与本地化

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

WAI-ARIA attributes and keyboard shortcuts
WCAG 2.2 / Section 508 / Screen reader support
CSS customization (chips, wrapper, icon, delimiter)
RTL support
Localization with
```
L10n
```

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

WAI-ARIA属性和键盘快捷键
WCAG 2.2 / Section 508 / 屏幕阅读器支持
CSS自定义（标签、包装器、图标、分隔符）
RTL支持
使用
```
L10n
```
进行本地化

API Reference

API参考

📄 Read: references/api.md

Complete list of all properties with types, descriptions, and defaults
All public methods with parameter details and return types
All events with their argument types and trigger conditions

📄 阅读： references/api.md

所有属性的完整列表，包含类型、描述和默认值
所有公共方法的参数详情和返回类型
所有事件的参数类型和触发条件

Key Props Reference

关键属性参考

Prop	Type	When to Use
`dataSource`	`string[] \| object[] \| DataManager`	Always required — data to display
`fields`	`FieldSettingsModel`	When using object data; map `text` , `value` , `groupBy` , `disabled`
`mode`	`'Default' \| 'Box' \| 'CheckBox' \| 'Delimiter'`	Change selection display: chips ( `Box` ), checkboxes, or comma-delimited
`value`	`string[] \| number[] \| object[]`	Pre-select items on load
`allowFiltering`	`boolean`	Enable search-as-you-type filtering
`allowCustomValue`	`boolean`	Let users type values not in the list
`allowObjectBinding`	`boolean`	Return full objects as selected values instead of primitives
`enableVirtualization`	`boolean`	Use for 500+ items to improve performance
`allowResize`	`boolean`	Let users resize the popup
`popupHeight`	`string`	Limit popup list height (default: `300px` )
`popupWidth`	`string`	Set popup width (default: matches input)
`placeholder`	`string`	Input placeholder text

属性	类型	使用场景
`dataSource`	`string[] \| object[] \| DataManager`	始终必填——要显示的数据
`fields`	`FieldSettingsModel`	使用对象数据时；映射 `text` 、 `value` 、 `groupBy` 、 `disabled`
`mode`	`'Default' \| 'Box' \| 'CheckBox' \| 'Delimiter'`	更改选择显示：标签（ `Box` ）、复选框或逗号分隔
`value`	`string[] \| number[] \| object[]`	加载时预选项
`allowFiltering`	`boolean`	启用输入即搜索筛选
`allowCustomValue`	`boolean`	允许用户输入列表中不存在的值
`allowObjectBinding`	`boolean`	返回完整对象作为选中值而非原始值
`enableVirtualization`	`boolean`	用于500+条数据以提升性能
`allowResize`	`boolean`	允许用户调整弹窗大小
`popupHeight`	`string`	限制弹窗列表高度（默认： `300px` ）
`popupWidth`	`string`	设置弹窗宽度（默认：匹配输入框）
`placeholder`	`string`	输入占位符文本

Common Use Cases

常见使用场景

Multi-tag input (chip display): → Use

mode="Box"

(default). Each selection becomes a chip.

Checkbox multi-selection: → Use

mode="CheckBox"

and inject

CheckBoxSelection

module.

Search/filter a long list: → Set

allowFiltering={true}

and handle the

filtering

event for remote data.

Pre-select values: → Pass

value

prop as an array of value-field values:

value={['id1', 'id2']}

Group by category: → Add

groupBy

to the

fields

prop:

fields={{ text: 'name', value: 'id', groupBy: 'category' }}

Large datasets (1000+ items): → Set

enableVirtualization={true}

and inject

VirtualScroll

module.

Disable specific options: → Add a boolean

disabled

column to your data and map it:

fields={{ ..., disabled: 'isDisabled' }}

Custom entry not in list: → Set

allowCustomValue={true}

; handle

customValueSelection

event for custom actions.

多标签输入（标签显示）： → 使用

mode="Box"

（默认）。每个选择项成为一个标签。

复选框多选： → 使用

mode="CheckBox"

并注入

CheckBoxSelection

模块。

长列表搜索/筛选： → 设置

allowFiltering={true}

并为远程数据处理

filtering

事件。

预选值： → 将

value

属性作为值字段值的数组传递：

value={['id1', 'id2']}

。

按类别分组： → 向

fields

属性添加

groupBy

：

fields={{ text: 'name', value: 'id', groupBy: 'category' }}

。

大型数据集（1000+条数据）： → 设置

enableVirtualization={true}

并注入

VirtualScroll

模块。

禁用特定选项： → 向数据添加布尔型

disabled

列并映射：

fields={{ ..., disabled: 'isDisabled' }}

。

列表中不存在的自定义输入： → 设置

allowCustomValue={true}

；处理

customValueSelection

事件以执行自定义操作。

Decision Guide

决策指南

User wants multiple selections?
  ├── Visual chips with filter → mode="Box" (default) + allowFiltering
  ├── Checkbox-style list      → mode="CheckBox" + Inject CheckBoxSelection
  └── Comma-separated display  → mode="Delimiter"

Data source type?
  ├── Simple strings/numbers   → Pass array directly to dataSource
  ├── Objects                  → Pass array + fields={{ text, value }}
  └── Remote API               → Use DataManager + allowFiltering + filtering event

List is very long?
  └── Yes (500+) → enableVirtualization={true} + Inject VirtualScroll

Need custom item layout?
  └── Use itemTemplate, valueTemplate, groupTemplate props

Need localization?
  └── Read references/accessibility-styling-localization.md

用户需要多选？
  ├── 带筛选的可视化标签 → mode="Box"（默认） + allowFiltering
  ├── 复选框样式列表      → mode="CheckBox" + Inject CheckBoxSelection
  └── 逗号分隔显示        → mode="Delimiter"

数据源类型？
  ├── 简单字符串/数字   → 直接传递数组到dataSource
  ├── 对象              → 传递数组 + fields={{ text, value }}
  └── 远程API           → 使用DataManager + allowFiltering + filtering事件

列表很长？
  └── 是（500+条）→ enableVirtualization={true} + Inject VirtualScroll

需要自定义项布局？
  └── 使用itemTemplate、valueTemplate、groupTemplate属性

需要本地化？
  └── 阅读references/accessibility-styling-localization.md

MultiColumn ComboBox

MultiColumn ComboBox组件

The Syncfusion

MultiColumnComboBoxComponent

renders a combo box with a multi-column popup grid, enabling users to select from structured tabular data. It supports local and remote data, filtering, sorting, grouping, templates, virtualization, and full accessibility compliance.

Package:

@syncfusion/ej2-react-multicolumn-combobox

Syncfusion

MultiColumnComboBoxComponent

渲染一个带多列弹窗网格的组合框，支持用户从结构化表格数据中选择。它支持本地和远程数据、筛选、排序、分组、模板、虚拟化以及完整的无障碍合规性。

包：

@syncfusion/ej2-react-multicolumn-combobox

Navigation Guide

导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup
CSS imports and theme configuration (Tailwind 3)
Rendering the first
```
MultiColumnComboBoxComponent
```
Binding
```
dataSource
```
,
```
fields
```
, and
```
columns
```
with
```
ColumnDirective
```
Configuring
```
popupHeight
```
and
```
popupWidth
```
Minimal working example (functional and class components)

📄 阅读： references/getting-started.md

安装与包设置
CSS导入与主题配置（Tailwind 3）
渲染第一个
```
MultiColumnComboBoxComponent
```
使用
```
ColumnDirective
```
绑定
```
dataSource
```
、
```
fields
```
和
```
columns
```
配置
```
popupHeight
```
和
```
popupWidth
```
最小工作示例（函数式和类组件）

Columns

列

📄 Read: references/columns.md

Defining columns with
```
ColumnDirective
```
and
```
ColumnsDirective
```
```
field
```
,
```
header
```
,
```
width
```
— core column properties
```
textAlign
```
for column text alignment
```
template
```
for cell-level custom rendering
```
displayAsCheckBox
```
for boolean columns
```
customAttributes
```
for column CSS customization
```
headerTemplate
```
for custom column headers
```
format
```
for data formatting

📄 阅读： references/columns.md

使用
```
ColumnDirective
```
和
```
ColumnsDirective
```
定义列
```
field
```
、
```
header
```
、
```
width
```
— 核心列属性
```
textAlign
```
用于列文本对齐
```
template
```
用于单元格级自定义渲染
```
displayAsCheckBox
```
用于布尔列
```
customAttributes
```
用于列CSS自定义
```
headerTemplate
```
用于自定义列标题
```
format
```
用于数据格式化

Data Binding

数据绑定

📄 Read: references/data-binding.md

Binding local object arrays via
```
dataSource
```
Remote data binding with
```
DataManager
```
and
```
WebApiAdaptor
```
Mapping
```
fields
```
(
```
text
```
,
```
value
```
,
```
groupBy
```
)
Using
```
query
```
property for filtered/limited data sets
OData, OData V4, Web API adaptor patterns

📄 阅读： references/data-binding.md

通过
```
dataSource
```
绑定本地对象数组
使用
```
DataManager
```
和
```
WebApiAdaptor
```
绑定远程数据
映射
```
fields
```
（
```
text
```
、
```
value
```
、
```
groupBy
```
）
使用
```
query
```
属性筛选/限制数据集
OData、OData V4、Web API适配器模式

Filtering

筛选

📄 Read: references/filtering.md

Enabling/disabling filtering with
```
allowFiltering
```
Changing filter mode with
```
filterType
```
(
```
StartsWith
```
,
```
EndsWith
```
,
```
Contains
```
)
```
filtering
```
event for custom filter logic
Disabling filtering for read-only scenarios

📄 阅读： references/filtering.md

使用
```
allowFiltering
```
启用/禁用筛选
使用
```
filterType
```
更改筛选模式（
```
StartsWith
```
、
```
EndsWith
```
、
```
Contains
```
）
```
filtering
```
事件用于自定义筛选逻辑
只读场景下禁用筛选

Sorting

排序

📄 Read: references/sorting.md

Enabling sorting with
```
allowSorting
```
Setting initial sort order with
```
sortOrder
```
(
```
None
```
,
```
Ascending
```
,
```
Descending
```
)
Sorting multiple columns with
```
sortType
```
(
```
OneColumn
```
,
```
MultipleColumns
```
)
Clicking column headers to toggle sort direction

📄 阅读： references/sorting.md

使用
```
allowSorting
```
启用排序
使用
```
sortOrder
```
设置初始排序顺序（
```
None
```
、
```
Ascending
```
、
```
Descending
```
）
使用
```
sortType
```
对多列排序（
```
OneColumn
```
、
```
MultipleColumns
```
）
点击列标题切换排序方向

Grouping

分组

📄 Read: references/grouping.md

Grouping data with
```
fields.groupBy
```
Fixed group headers in popup
Using
```
groupTemplate
```
to customize group headers

📄 阅读： references/grouping.md

使用
```
fields.groupBy
```
分组数据
弹窗中的固定分组标题
使用
```
groupTemplate
```
自定义分组标题

Templates

模板

📄 Read: references/templates.md

```
itemTemplate
```
for customizing each row
```
headerTemplate
```
(on
```
ColumnDirective
```
) for custom column headers
```
groupTemplate
```
for group header customization
```
footerTemplate
```
for popup footer content
```
noRecordsTemplate
```
for empty state display
```
actionFailureTemplate
```
for remote fetch error state

📄 阅读： references/templates.md

```
itemTemplate
```
用于自定义每行
```
headerTemplate
```
（在
```
ColumnDirective
```
上）用于自定义列标题
```
groupTemplate
```
用于分组标题自定义
```
footerTemplate
```
用于弹窗底部内容
```
noRecordsTemplate
```
用于空状态显示
```
actionFailureTemplate
```
用于远程获取错误状态

Items and Configuration

项与配置

📄 Read: references/items.md

Setting initial selection with
```
text
```
,
```
value
```
,
```
index
```
```
placeholder
```
and
```
floatLabelType
```
for input label behavior
```
showClearButton
```
to allow clearing selection
```
disabled
```
and
```
readonly
```
states
```
width
```
,
```
popupWidth
```
,
```
popupHeight
```
for sizing
```
cssClass
```
for custom styling
```
htmlAttributes
```
for additional HTML attributes
```
gridSettings
```
for grid lines, row height, and alternate rows
```
query
```
for data constraints

addItems

method,

focusIn

focusOut

showPopup

hidePopup

📄 阅读： references/items.md

使用
```
text
```
、
```
value
```
、
```
index
```
设置初始选择
```
placeholder
```
和
```
floatLabelType
```
用于输入标签行为
```
showClearButton
```
允许清除选择
```
disabled
```
和
```
readonly
```
状态
```
width
```
、
```
popupWidth
```
、
```
popupHeight
```
用于尺寸设置
```
cssClass
```
用于自定义样式
```
htmlAttributes
```
用于附加HTML属性
```
gridSettings
```
用于网格线、行高和交替行
```
query
```
用于数据约束

addItems

方法、

focusIn

、

focusOut

、

showPopup

、

hidePopup

Virtualization

虚拟化

📄 Read: references/virtualization.md

Enabling
```
enableVirtualization
```
for large datasets
Virtual scrolling with local and remote data
Combining with
```
gridSettings.rowHeight
```

📄 阅读： references/virtualization.md

为大型数据集启用
```
enableVirtualization
```
本地和远程数据的虚拟滚动
与
```
gridSettings.rowHeight
```
结合使用

Events

事件

📄 Read: references/events.md

```
change
```
— fired when value changes or item is selected
```
select
```
— fired on item selection
```
open
```
/
```
close
```
— popup open/close lifecycle
```
filtering
```
— fired on character input for custom filtering
```
actionBegin
```
/
```
actionComplete
```
/
```
actionFailure
```
— data fetch lifecycle

📄 阅读： references/events.md

```
change
```
— 值更改或项选中时触发
```
select
```
— 项选中时触发
```
open
```
/
```
close
```
— 弹窗打开/关闭生命周期
```
filtering
```
— 用户输入字符时触发，用于自定义筛选
```
actionBegin
```
/
```
actionComplete
```
/
```
actionFailure
```
— 数据获取生命周期

API Reference

API参考

📄 Read: references/api.md

Complete list of all properties with types and defaults
All events with their argument types

All methods:

addItems

focusIn

focusOut

getDataByValue

getItems

showPopup

hidePopup

```
ColumnModel
```
properties
```
GridSettingsModel
```
properties
```
FieldSettingsModel
```
properties

📄 阅读： references/api.md

所有属性的完整列表，包含类型和默认值
所有事件的参数类型

所有方法：

addItems

、

focusIn

、

focusOut

、

getDataByValue

、

getItems

、

showPopup

、

hidePopup

```
ColumnModel
```
属性
```
GridSettingsModel
```
属性
```
FieldSettingsModel
```
属性

Accessibility

无障碍

📄 Read: references/accessibility.md

WCAG 2.2 and Section 508 compliance
WAI-ARIA attributes (
```
role
```
,
```
aria-expanded
```
,
```
aria-selected
```
, etc.)
Keyboard navigation shortcuts
RTL support with
```
enableRtl
```
Screen reader support

📄 阅读： references/accessibility.md

WCAG 2.2和Section 508合规性
WAI-ARIA属性（
```
role
```
、
```
aria-expanded
```
、
```
aria-selected
```
等）
键盘导航快捷键
使用
```
enableRtl
```
的RTL支持
屏幕阅读器支持

Localization

本地化

📄 Read: references/localization.md

Localizing
```
noRecordsTemplate
```
text using
```
L10n
```
Setting
```
locale
```
property for culture-specific rendering
Loading translation objects

📄 阅读： references/localization.md

使用
```
L10n
```
本地化
```
noRecordsTemplate
```
文本
设置
```
locale
```
属性以实现特定文化的渲染
加载翻译对象

Quick Start

快速入门

tsx

import { MultiColumnComboBoxComponent, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-multicolumn-combobox';
import * as React from 'react';
import './App.css';

// CSS in 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-grids/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-multicolumn-combobox/styles/tailwind3.css";

function App() {
  const empData = [
    { EmpID: 1001, Name: 'Andrew Fuller', Designation: 'Team Lead', Country: 'England' },
    { EmpID: 1002, Name: 'Robert', Designation: 'Developer', Country: 'USA' },
    { EmpID: 1003, Name: 'Michael', Designation: 'HR', Country: 'Russia' },
  ];
  const fields = { text: 'Name', value: 'EmpID' };

  return (
    <MultiColumnComboBoxComponent
      id="multicolumn"
      dataSource={empData}
      fields={fields}
      placeholder="Select an employee"
    >
      <ColumnsDirective>
        <ColumnDirective field='EmpID' header='Employee ID' width={120} />
        <ColumnDirective field='Name' header='Name' width={120} />
        <ColumnDirective field='Designation' header='Designation' width={120} />
        <ColumnDirective field='Country' header='Country' width={100} />
      </ColumnsDirective>
    </MultiColumnComboBoxComponent>
  );
}
export default App;

tsx

import { MultiColumnComboBoxComponent, ColumnsDirective, ColumnDirective } from '@syncfusion/ej2-react-multicolumn-combobox';
import * as React from 'react';
import './App.css';

// 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-grids/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-popups/styles/tailwind3.css";
// @import "../node_modules/@syncfusion/ej2-react-multicolumn-combobox/styles/tailwind3.css";

function App() {
  const empData = [
    { EmpID: 1001, Name: 'Andrew Fuller', Designation: 'Team Lead', Country: 'England' },
    { EmpID: 1002, Name: 'Robert', Designation: 'Developer', Country: 'USA' },
    { EmpID: 1003, Name: 'Michael', Designation: 'HR', Country: 'Russia' },
  ];
  const fields = { text: 'Name', value: 'EmpID' };

  return (
    <MultiColumnComboBoxComponent
      id="multicolumn"
      dataSource={empData}
      fields={fields}
      placeholder="Select an employee"
    >
      <ColumnsDirective>
        <ColumnDirective field='EmpID' header='Employee ID' width={120} />
        <ColumnDirective field='Name' header='Name' width={120} />
        <ColumnDirective field='Designation' header='Designation' width={120} />
        <ColumnDirective field='Country' header='Country' width={100} />
      </ColumnsDirective>
    </MultiColumnComboBoxComponent>
  );
}
export default App;

Common Patterns

常见模式

Pre-select an item by text

通过文本预选项

tsx

<MultiColumnComboBoxComponent dataSource={empData} fields={fields} text="Michael">
  {/* columns */}
</MultiColumnComboBoxComponent>

tsx

<MultiColumnComboBoxComponent dataSource={empData} fields={fields} text="Michael">
  {/* columns */}
</MultiColumnComboBoxComponent>

Enable filtering with Contains mode

启用包含模式的筛选

tsx

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  allowFiltering={true}
  filterType="Contains"
>
  {/* columns */}
</MultiColumnComboBoxComponent>

tsx

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  allowFiltering={true}
  filterType="Contains"
>
  {/* columns */}
</MultiColumnComboBoxComponent>

Enable sorting (descending) with multi-column support

启用（降序）排序并支持多列

tsx

import { SortOrder } from '@syncfusion/ej2-react-multicolumn-combobox';

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  allowSorting={true}
  sortOrder={SortOrder.Descending}
  sortType="MultipleColumns"
>
  {/* columns */}
</MultiColumnComboBoxComponent>

tsx

import { SortOrder } from '@syncfusion/ej2-react-multicolumn-combobox';

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  allowSorting={true}
  sortOrder={SortOrder.Descending}
  sortType="MultipleColumns"
>
  {/* columns */}
</MultiColumnComboBoxComponent>

Handle value change event

处理值更改事件

tsx

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  change={(args) => console.log('Selected:', args.value)}
>
  {/* columns */}
</MultiColumnComboBoxComponent>

tsx

<MultiColumnComboBoxComponent
  dataSource={empData}
  fields={fields}
  change={(args) => console.log('Selected:', args.value)}
>
  {/* columns */}
</MultiColumnComboBoxComponent>