syncfusion-react-list-box

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion React ListBox

实现 Syncfusion React ListBox

The ListBox component is a versatile React dropdown-alternative that displays items in a scrollable list format. It supports single/multiple selection, custom templates, drag-and-drop, filtering, and grouping, making it ideal for building accessible, feature-rich selection interfaces.

ListBox 组件是一款功能丰富的 React 下拉菜单替代方案，以可滚动列表的形式展示选项。它支持单选/多选、自定义模板、拖拽、筛选和分组，非常适合开发无障碍、功能完备的选择交互界面。

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)

双列表框（转移）

📄 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

快速上手示例

Basic ListBox with single selection:

tsx

import { ListBoxComponent } from '@syncfusion/ej2-react-dropdowns';
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;

基础单选 ListBox：

tsx

import { ListBoxComponent } from '@syncfusion/ej2-react-dropdowns';
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 合规

需要帮助？ 每个参考文件都包含示例、边缘情况说明和故障排查技巧。