syncfusion-angular-listview

实现 Syncfusion Angular ListView

Syncfusion Angular ListView 组件功能丰富、交互性强，可用于以列表形式显示数据。它内置支持数据绑定、分组、嵌套列表、自定义模板、选择模式、拖放、大型数据集虚拟化以及全面的无障碍功能。该组件已可用于生产环境，适合构建现代化的数据驱动用户界面。

何时使用此技能

在以下情况下使用此技能：

• 使用 Angular 构建基于列表的交互式界面
• 显示来自本地或远程数据源的数据
• 创建分组或嵌套列表结构
• 使用模板自定义列表项外观
• 处理项目选择和用户交互
• 实现特定模式（聊天窗口、清单、双列表）
• 使用虚拟化优化大型数据集的性能
• 构建无障碍列表界面

组件概述

包： @syncfusion/ej2-angular-lists

主要功能：

• ✅ 本地和远程数据绑定（数组、DataManager、OData、REST API）
• ✅ 分组和嵌套列表层级结构
• ✅ 灵活的项目、标题和分组模板
• ✅ 单选／多选模式和复选框
• ✅ 完整的事件系统（选择、点击、删除、添加、移除）
• ✅ 支持拖放重新排序
• ✅ 针对大型数据集的虚拟化（1000+ 个项目）
• ✅ AJAX 内容加载和动态模板
• ✅ 集成分页支持
• ✅ 全面的主题和样式选项
• ✅ 符合 WCAG 无障碍标准

---

文档与导航指南

入门

📄 阅读： references/getting-started.md

• Angular CLI 设置和项目配置
• 安装 @syncfusion/ej2-angular-lists 包
• 添加 CSS 主题和样式
• 创建第一个 ListView 组件
• 使用精简示例进行基本数据绑定
• 运行应用程序（ng serve）

数据绑定

📄 阅读： references/data-binding.md

• 绑定本地数据数组（字符串、对象）
• 字段配置和数据映射
• 使用 DataManager 进行远程数据绑定
• OData 和 REST API 集成
• 动态数据更新和刷新策略
• 字段属性：id、text、isChecked、enabled、tooltip、groupBy

自定义与模板

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

• 使用按钮和搜索栏自定义标题模板
• 包含头像、徽章和多行布局的项目模板
• 带动态内容的分组标题模板
• 根据设备或屏幕尺寸使用动态模板
• 内置 CSS 类（e-list-template、e-list-wrapper、e-list-avatar 等）
• 带数据绑定的高级模板模式

分组与嵌套列表

📄 阅读： references/grouping-and-nested-lists.md

• 使用 groupBy 字段按类别对项目分组
• 自定义分组标题和模板
• 为分层数据创建嵌套列表结构
• 子数据绑定和可展开分组
• 使用项目计数自定义分组标题

选择与项目管理

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

• 选择模式（单选、多选、复选框）
• 使用 getSelectedItems() 方法获取选中项目
• 使用 addItem() 动态添加项目
• 使用 removeItem() 移除项目
• 事件处理（select、actionComplete）
• 以编程方式选择和取消选择

高级功能

📄 阅读： references/advanced-features.md

• 针对高性能大型数据集的虚拟化
• 滚动和滚动位置管理
• 拖放以重新排序项目
• 筛选和搜索列表项目
• 将分页组件与 ListView 集成
• 数据获取期间的加载状态和微调器
• 将 AJAX 内容加载到列表项目中

专用用例

📄 阅读： references/specialized-use-cases.md

• 构建聊天窗口布局
• 创建带复选框的清单界面
• 构建双列表（传输列表）组件
• 使用 ListView 创建网格布局
• 渲染带超链接的导航列表
• 使用动态标签和徽章进行自定义
• 移动端联系人布局模式

样式和主题

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

• 导入主题（Material3、Bootstrap、Fabric、Tailwind）
• 自定义和覆盖 CSS 类
• 为列表项和分组设置自定义样式
• 响应式设计和移动端优化
• 动画设置和过渡效果
• RTL（从右到左）支持
• 暗色模式主题

项目计数和分组标题

📄 阅读： references/item-count-and-grouping.md

• 在分组标题中显示项目计数
• 动态计算和更新计数
• 分组统计和聚合
• 高级分组标题模板
• 有条件地显示项目计数

无障碍访问

📄 阅读： references/accessibility.md

• 符合 WCAG 2.1 标准并支持键盘导航
• ARIA 属性和屏幕阅读器支持
• 焦点管理和指示器
• 键盘快捷键和导航模式
• 色彩对比度和无障碍主题
• 使用辅助技术测试无障碍功能

完整 API 参考

📄 阅读： references/api-reference.md

• 属性：animation、enablePersistence、enableRtl、locale、query 等
• 方法：back()、checkAllItems()、selectMultipleItems() 及完整的方法集
• 事件：select、scroll、actionBegin、actionComplete、actionFailure，附带参数详情
• 每个 API 的完整可运行示例
• 属性、方法和事件的速查表

---

快速入门示例

import { ListViewModule } from '@syncfusion/ej2-angular-lists';
import { Component } from '@angular/core';

@Component({
  imports: [ListViewModule],
  standalone: true,
  selector: 'app-root',
  template: `
    <ejs-listview 
      id='sample-list' 
      [dataSource]='data'>
    </ejs-listview>
  `
})
export class AppComponent {
  // Simple string data
  public data: string[] = [
    'Artwork', 'Abstract', 'Modern Painting', 
    'Ceramics', 'Animation Art', 'Oil Painting'
  ];
}

CSS 导入（在 styles.css 中）：

@import "../node_modules/@syncfusion/ej2-base/styles/material3.css";
@import "../node_modules/@syncfusion/ej2-angular-lists/styles/material3.css";

运行：

npm install @syncfusion/ej2-angular-lists --save
ng serve --open

---

常见模式

模式 1：使用字段映射的数据驱动列表

适用于显示具有多个属性的复杂对象：

public data = [
  { name: 'John', email: '[email protected]', id: '1' },
  { name: 'Jane', email: '[email protected]', id: '2' }
];
public fields = { text: 'name', id: 'id' };

模式 2：分组列表

适用于按类别整理项目：

public fields = { text: 'name', groupBy: 'department' };

模式 3：模板化列表

适用于需要自定义布局的场景：

<ejs-listview [dataSource]='data' cssClass='e-list-template'>
  <ng-template #template let-data="">
    <div class="e-list-wrapper">
      <span>{{ data.name }}</span>
    </div>
  </ng-template>
</ejs-listview>

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

适用于用户需要选择多个项目的场景：

<ejs-listview [dataSource]='data' [showCheckBox]='true'></ejs-listview>

模式 5：动态添加/移除

适用于交互式列表管理：

addItem() {
  this.listview.addItem([{ text: 'New Item', id: 'new' }]);
}
removeItem(element: HTMLElement) {
  this.listview.removeItem(element);
}

---

主要属性和配置

属性	类型	描述
dataSource	array/DataManager	要在列表中显示的数据
fields	object	字段映射（text、id、groupBy 等）
template	string/function	列表项的自定义模板
headerTemplate	string/function	自定义标题模板
groupTemplate	string/function	自定义分组标题模板
showCheckBox	boolean	显示用于选择的复选框（默认值：false）
showHeader	boolean	显示 ListView 标题（默认值：false）
headerTitle	string	标题文本
enableVirtualization	boolean	为大型数据集启用虚拟滚动
enableHtmlSanitizer	boolean	清理 HTML 内容（默认值：true）
allowDragAndDrop	boolean	启用拖放排序
select	event	选择项目时触发
actionComplete	event	添加/移除操作完成后触发

---

常见用例

1. 任务管理器 - 使用复选框和拖放功能动态添加或移除任务
2. 联系人目录 - 使用多行模板，并按部门分组
3. 聊天界面 - 使用包含头像和时间戳的自定义模板
4. 产品目录 - 使用虚拟化功能处理数千种产品
5. 导航菜单 - 使用带图标和路由的嵌套列表
6. 清单 - 使用复选框选择，并在标题中显示计数
7. 双列表传输 - 使用两个 ListView 并执行移动操作
8. 移动端导航 - 采用便于触控的响应式列表布局

---

后续步骤

• 从这里开始： 入门指南
• 绑定数据： 数据绑定
• 构建交互功能： 选择和项目
• 优化性能： 高级功能
• 高级模式： 专用用例

如需查看 API 参考和详细文档，请参阅 Syncfusion Angular ListView API。