syncfusion-react-listview

实现 Syncfusion React ListView

全面介绍如何实现 Syncfusion React ListView 组件，以显示动态、交互式列表，并支持模板、筛选、选择和数据管理等高级功能。

何时使用此技能

在以下场景中使用此技能：

• 使用丰富的模板和自定义选项显示项目列表
• 实现单选或多选
• 动态添加、移除或更新列表项
• 筛选和搜索列表数据
• 创建嵌套列表或分组列表
• 处理用户交互（滚动、选择、勾选）
• 应用自定义动画和样式
• 支持拖放操作
• 使用虚拟化优化性能
• 实现数据绑定（本地或远程）
• 添加复选框或自定义图标
• 提供无障碍功能（WCAG 2.1）

组件概览

ListView 组件会在可滚动的交互式列表中显示一组项目。它支持：

• **数据源：**数组、对象、DataManager、远程 API
• **选择模式：**无、单选、多选或基于复选框的选择
• **模板：**项目模板、标题模板、分组模板
• **数据操作：**筛选、排序、分组、搜索
• **性能：**支持 1000+ 个项目的虚拟滚动
• **交互：**单击、选择、滚动事件
• **样式：**内置主题、自定义 CSS、RTL 支持
• **无障碍：**符合 WCAG 2.1 AA 级标准

安装与设置

第 1 步：安装 Syncfusion 包

npm install @syncfusion/ej2-react-lists @syncfusion/ej2-base @syncfusion/ej2-data

第 2 步：导入所需模块

import { ListViewComponent } from '@syncfusion/ej2-react-lists';
// For additional features:
import { Inject, Virtualization } from '@syncfusion/ej2-react-lists';

第 3 步：导入 CSS

import '@syncfusion/ej2-react-lists/styles/material.css'; // or other themes

快速入门示例

import React from 'react';
import { ListViewComponent } from '@syncfusion/ej2-react-lists';

export function BasicListView() {
  const data = [
    { id: '1', text: 'Item 1' },
    { id: '2', text: 'Item 2' },
    { id: '3', text: 'Item 3' }
  ];

  return (
    <ListViewComponent
      id="list"
      dataSource={data}
      fields={{ text: 'text', id: 'id' }}
    />
  );
}

核心概念

1. 数据绑定

本地数组：

const items = ['Apple', 'Banana', 'Orange'];
<ListViewComponent dataSource={items} />

带映射的对象数组：

const data = [
  { productId: 1, productName: 'Laptop', category: 'Electronics' },
  { productId: 2, productName: 'Desk', category: 'Furniture' }
];

<ListViewComponent
  dataSource={data}
  fields={{
    id: 'productId',
    text: 'productName',
    groupBy: 'category'
  }}
/>

2. 选择处理

const handleSelect = (args) => {
  console.log('Selected item:', args.text, args.id);
};

<ListViewComponent
  dataSource={data}
  select={handleSelect}
/>

3. 项目管理

• 添加项目：addItem(data, fields?)
• 移除项目：removeItem(item)
• **更新项目：**在 dataSource 中替换并刷新
• 获取所选项目：getSelectedItems()

4. 模板

// Item Template
const itemTemplate = (props) => (
  <div className="e-list-wrapper">
    <span>{props.text}</span>
    <span className="e-list-content">{props.category}</span>
  </div>
);

<ListViewComponent
  dataSource={data}
  fields={fields}
  template={itemTemplate}
/>

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和导入
• 基本设置和第一个组件
• CSS 主题和样式
• 最简可运行示例
• 项目结构

数据绑定与渲染

📄 阅读： references/data-binding-rendering.md

• 本地数组数据源
• 使用字段映射对象
• 使用 DataManager 处理远程数据
• 对远程数据进行查询筛选
• 按需加载和分页
• 动态数据更新

项目管理（CRUD）

📄 阅读： references/item-management.md

• 动态添加新项目
• 按引用移除项目
• 更新现有项目
• 批量操作
• 在列表中查找项目
• 管理嵌套列表项

选择与筛选

📄 阅读： references/selection-filtering.md

• 单项选择
• 多项选择
• 基于复选框的选择
• 以编程方式选择
• 筛选列表项
• 搜索功能
• 选择事件和回调

模板与自定义

📄 阅读： references/templating-customization.md

• 自定义项目模板（JSX、函数、字符串）
• 使用 headerTemplate 设置标题模板
• 使用 groupTemplate 设置分组标题模板
• 模板数据上下文和变量
• 根据设备动态设置模板
• 使用类自定义 CSS
• RTL 模板支持

高级功能

📄 阅读： references/advanced-features.md

• 分组和排序
• 带层级结构的嵌套列表（最多 3 层）
• 复选框状态管理
• 动画和效果
• 自定义图标和图像显示
• 启用或禁用项目状态
• 复杂仪表板的布局模式

布局与对齐模式 ⭐ 新

📄 阅读： references/layout-alignment-patterns.md

• 患者门户模式： 使用 ListView 展示卡片、预约、处方和消息
• 预约仪表板： 3x2 网格布局，包含筛选器、日程安排器和分析
• 监控仪表板： 3x3 网格布局，包含 KPI、警报和工单
• 修复常见的对齐问题（滚动、边框、间距）
• 适用于手机、平板和桌面的响应式网格布局
• 每种模式的完整代码示例

性能与虚拟化

📄 阅读： references/performance-virtualization.md

• 对大型数据集（1000+）使用虚拟滚动
• 启用虚拟化
• 刷新项目高度
• 内存优化技巧
• 与分页结合使用
• 性能最佳实践
• 数据集大小建议

API 参考与属性

📄 阅读： references/api-reference.md

• 完整的属性文档
• 方法签名和参数
• 事件处理程序参数
• 所有属性的默认值
• 属性类型规范
• 每个 API 的用法示例

无障碍访问与事件

📄 阅读： references/accessibility-events.md

• 符合 WCAG 2.1 标准
• 键盘导航
• 屏幕阅读器支持
• ARIA 属性
• 焦点管理
• 事件生命周期
• 事件参数和数据

常见模式

模式 1：带选择功能的列表

用户点击项目 → 触发选择事件 → 更新 UI

const [selected, setSelected] = React.useState(null);

const handleSelect = (args) => {
  setSelected(args);
};

<ListViewComponent
  dataSource={items}
  select={handleSelect}
/>

模式 2：添加/移除项目

const listViewRef = React.useRef(null);

const addItem = () => {
  listViewRef.current.addItem([{ text: 'New Item', id: Date.now() }]);
};

const removeItem = (item) => {
  listViewRef.current.removeItem(item);
};

<ListViewComponent ref={listViewRef} dataSource={items} />

模式 3：筛选列表

const [filteredData, setFilteredData] = React.useState(items);

const handleFilter = (searchText) => {
  const filtered = items.filter(item =>
    item.text.toLowerCase().includes(searchText.toLowerCase())
  );
  setFilteredData(filtered);
};

<ListViewComponent dataSource={filteredData} />

模式 4：使用复选框进行多选

<ListViewComponent
  dataSource={items}
  showCheckBox={true}
  fields={{ id: 'id', text: 'text', isChecked: 'checked' }}
/>

模式 5：卡片容器中的 ListView（新）

<div style={{
  border: '1px solid #e0e0e0',
  borderRadius: '4px',
  overflow: 'hidden',
  display: 'flex',
  flexDirection: 'column'
}}>
  <div style={{
    padding: '16px',
    backgroundColor: '#f5f5f5',
    borderBottom: '1px solid #e0e0e0'
  }}>
    <h3 style={{ margin: 0 }}>Messages</h3>
  </div>
  <div style={{ flex: 1, overflow: 'auto', minHeight: 0 }}>
    <ListViewComponent
      dataSource={items}
      height="100%"
      width="100%"
    />
  </div>
</div>

模式 6：网格布局中的 ListView（新）

<div style={{
  display: 'grid',
  gridTemplateColumns: 'repeat(3, 1fr)',
  gap: '16px'
}}>
  {/* Card 1 - ListView */}
  <div style={{ border: '1px solid #e0e0e0', display: 'flex', flexDirection: 'column' }}>
    <div style={{ padding: '12px', backgroundColor: '#f5f5f5' }}>Appointments</div>
    <div style={{ flex: 1, overflow: 'auto', minHeight: 0 }}>
      <ListViewComponent dataSource={appointments} height="300px" />
    </div>
  </div>
  {/* Card 2, Card 3, etc. */}
</div>

模式 7：包含多个 ListView 的仪表板（新）

请参阅布局与对齐模式指南，了解：

• 🏥 患者门户： 预约 + 消息 + 处方网格
• 📅 预约仪表板： 包含筛选器和日程安排器的 3x2 网格
• 📊 监控仪表板： 包含 KPI、日志、警报和工单的 3x3 网格

关键属性

属性	类型	默认值	用途
dataSource	Array/DataManager	[]	要显示的数据
fields	FieldSettingsModel	defaultMappedFields	将数据映射到字段
template	string/function/JSX	null	自定义项目模板
headerTemplate	string/function/JSX	null	自定义标题模板
groupTemplate	string/function/JSX	null	自定义分组模板
showCheckBox	boolean	false	显示复选框
checkBoxPosition	'Left'|'Right'	'Left'	复选框位置
sortOrder	'None'|'Ascending'|'Descending'	'None'	数据排序顺序
enableVirtualization	boolean	false	虚拟滚动
height	number|string	''	列表高度
width	number|string	''	列表宽度
cssClass	string	''	自定义 CSS 类
enabled	boolean	true	启用/禁用组件
enableRtl	boolean	false	从右到左支持
animation	AnimationSettings	{...}	项目动画

关键方法

方法	用途
addItem(data, fields?)	向列表添加新项目
removeItem(item)	从列表中移除项目
removeMultipleItems(items)	一次移除多个项目
selectItem(item)	选择一个项目
selectMultipleItems(items)	选择多个项目
unselectItem(item?)	取消选择项目
getSelectedItems()	获取当前选择
findItem(item)	查找项目详情
checkItem(item)	勾选复选框项目
uncheckItem(item)	取消勾选复选框项目
checkAllItems()	勾选所有项目
uncheckAllItems()	取消勾选所有项目
enableItem(item)	启用已禁用的项目
disableItem(item)	禁用项目
hideItem(item)	隐藏项目
showItem(item)	显示隐藏的项目
back()	从嵌套列表返回
refreshItemHeight()	刷新项目高度（虚拟化）
destroy()	清理组件

关键事件

事件	触发时机
select	选择项目时
actionBegin	开始任何操作时
actionComplete	完成任何操作时
actionFailure	远程数据获取失败时
scroll	用户滚动到顶部或底部时

常见用例

1. 显示设置列表： 带图标的分组项目
2. 联系人列表： 带图片的多行模板
3. 嵌套导航： 逐层深入的层级结构
4. 可筛选搜索： 动态筛选数据
5. 待办事项列表： 复选框和项目移除
6. 产品目录： 分页和筛选
7. 聊天消息： 按日期倒序分组
8. 通知流： 支持滚动和操作
9. 多选选择器： 复选框和按钮
10. 层级菜单： 带返回导航的嵌套项目

提示与最佳实践

通用最佳实践

• ✅ 始终正确映射 fields，以显示数据
• ✅ 使用模板呈现纯文本之外的丰富界面
• ✅ 项目超过 1000 个时启用虚拟化
• ✅ 使用 DataManager 筛选或排序大型远程数据
• ✅ 对模板和回调进行记忆化处理，以避免重新渲染
• ✅ 使用 cssClass 进行轻量级自定义
• ✅ 处理 select 事件以响应用户交互
• ✅ 组件卸载时使用 destroy() 进行清理
• ❌ 不要在每个项目模板中渲染复杂组件
• ❌ 不要忘记设置正确的 fields 映射

对齐与布局最佳实践 ⭐

• ✅ 使用 flex 布局时，始终为父容器设置明确的 height
• ✅ 在 flex 子元素上使用 overflow: 'auto' 和 minHeight: 0，以支持滚动
• ✅ 在页眉上使用 flexShrink: 0，防止其收缩
• ✅ 在模板中使用 gap，而非单独设置边距，以保持间距一致
• ✅ 为 ListView 设置 width: '100%' 和 height: '100%'，使其填满容器
• ✅ 将 ListView 包裹在 flex 容器中，并设置 display: 'flex' 和 flexDirection: 'column'
• ✅ 使用 CSS Grid 构建仪表板布局，并正确设置 gridColumn/gridRow
• ✅ 在卡片容器上设置 overflow: 'hidden'，以适应圆角边框
• ❌ 不要依赖默认边距——它们会导致对齐不一致
• ❌ 不要跳过 flex 容器设置——ListView 需要正确的父级上下文
• ❌ 不要忘记为 flex 中的滚动容器设置 minHeight: 0

故障排除

项目未显示？

• 确认 dataSource 已填充
• 检查 fields 映射是否与数据结构匹配
• 确保正确映射了 text 字段

选择不起作用？

• 确认已绑定 select 事件处理程序
• 检查项目是否有有效的 id 字段
• 确保项目未被禁用

性能问题？

• 启用 enableVirtualization={true}
• 降低模板复杂度
• 使用 DataManager 进行远程筛选，而非客户端筛选

样式问题？

• 导入 CSS 主题文件
• 检查是否已将 cssClass 应用于根元素
• 检查 CSS 优先级冲突

---

后续步骤：

• 根据用例阅读相应的参考文件
• 查阅 API 参考，了解完整的属性和方法文档
• 查看无障碍指南，确保符合 WCAG 标准
• 探索适用于特定功能的代码示例