syncfusion-react-list-box

用途

Syncfusion React ListBox 是一个 React 列表选择组件，作为下拉框的替代方案，以可滚动列表形式展示项目。它适用于构建可访问、功能丰富的选择界面，例如从列表中选择框架、多选语言、技能选择器、拖放传输、分组分类、可搜索列表以及无障碍菜单等场景。

主要能力

选择模式：支持单选（Single）和多选（Multiple），并支持复选框选择（需注入 CheckBoxSelection 服务）。
数据绑定：支持数组和对象数据绑定，通过 fields 映射 text 和 value 属性，支持分组数据与层级数据结构。
模板与图标：支持在项目中渲染图标、自定义项目模板、HTML 内容渲染、模板变量与语法以及条件渲染。
高级功能：支持拖放、过滤与搜索、排序与分组、双列表（传输列表）、滚动条配置以及项目启用/禁用。
样式与外观：支持 CSS 类自定义、主题集成、项目与分组样式、响应式设计以及自定义 CSS 变量。
无障碍：支持 WCAG 2.2 合规、键盘导航、ARIA 属性、屏幕阅读器支持以及 RTL（从右到左）支持。

使用方式

文档按主题组织，用户可根据实现需求导航到具体主题：

入门（references/getting-started.md）：React 应用设置（Vite/Create React App）、安装 Syncfusion 包、CSS 导入与主题、创建基本 ListBox 组件、运行应用。
选择与事件（references/selection.md）：单选模式、多选模式、选择事件与处理程序、编程式选择管理、处理选中项目。
数据绑定与结构（references/data-binding.md）：数组和对象数据绑定、text 和 value 属性、数据源配置、分组数据、层级数据结构。
自定义模板与图标（references/icons-and-templates.md）：项目中图标渲染、自定义项目模板、HTML 内容渲染、模板变量与语法、条件渲染。
高级功能（references/features.md）：拖放功能、过滤与搜索、排序与分组、双 ListBox（传输列表）、滚动条配置、项目启用/禁用。
样式与外观（references/style-and-appearance.md）：CSS 类自定义、主题集成、项目与分组样式、响应式设计、自定义 CSS 变量。
无障碍（references/accessibility.md）：WCAG 2.2 合规、键盘导航、ARIA 属性、屏幕阅读器支持、RTL 支持。
操作指南（references/how-to-guides.md）：动态添加项目、编程式选择项目、启用/禁用项目、过滤 ListBox 数据、为长列表启用滚动条、表单集成与提交、双 ListBox（传输）。
双 ListBox（传输）（references/dual-list-box.md）：两个列表之间的双向项目传输、工具栏操作（上移/下移、传输）、权限与技能分配模式、自定义样式与响应式设计、容量限制与验证。
API 参考（references/api.md）：所有属性及其类型和默认值的完整列表、所有公共方法及其参数详情和返回类型、所有事件及其完整事件参数接口、子接口（SelectionSettingsModel、ToolbarSettingsModel、FieldSettingsModel、SourceDestinationModel）。

快速开始示例（基本单选 ListBox）：

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;

常见模式：

多选：

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

复选框选择（需注入 CheckBoxSelection 服务）：

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

const selectionSettings: SelectionSettingsModel = { showCheckbox: true };

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

带搜索/过滤：

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

自定义项目模板：

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

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

分组项目：

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

关键属性与配置：

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

适用场景

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

限制

资料中未明确列出该组件的具体限制。复选框选择需要注入 CheckBoxSelection 服务。

技能介绍

用途

主要能力

使用方式

适用场景

限制