syncfusion-aspnetcore-listview

在 ASP.NET Core 中实现 ListView

ListView 组件是一种功能强大的控件，可在交互式分层结构中显示数据。它支持数据绑定（本地和远程）、分组、嵌套列表、自定义模板、用于提升性能的虚拟化，以及全面的键盘无障碍支持。

何时使用此技能

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

• 显示交互式列表：呈现数据集合，并支持点击选择、悬停效果和视觉反馈
• 对相关项进行分组：使用 groupBy 字段将列表项整理到不同类别中
• 支持嵌套导航：通过父子关系创建多级层次结构
• 优化性能：通过 UI 虚拟化处理大型数据集（1000+ 项）
• 自定义外观：为页眉、项和分组标题应用模板
• 启用选择功能：使用复选框实现单选或多选
• 处理远程数据：使用 DataManager 和 Query 绑定到服务器 API
• 实现键盘操作：支持键盘导航，提升无障碍性

组件概览

Syncfusion EJ2 for ASP.NET Core 中的 ListView 组件使用 TagHelper 语法，并公开核心属性：

类别	关键属性
数据绑定	dataSource、fields、query
显示控制	template、headerTemplate、groupTemplate
用户交互	showCheckBox、checkBoxPosition、sortOrder
性能	enableVirtualization、height
外观	cssClass、width、showHeader、showIcon
无障碍性	enableRtl、事件处理程序

文档和导航指南

入门与数据绑定

📄 阅读： references/getting-started-and-data-binding.md

• ASP.NET Core 项目设置和 TagHelper 导入
• DataSource 属性的不同形式（数组、JSON、远程）
• 文本、ID 和嵌套属性的字段映射
• 使用 DataManager 和 Query 进行远程数据绑定
• ListView 基本初始化示例

字段设置与配置

📄 阅读： references/field-settings-and-configuration.md

• 完整的字段映射选项（14 个属性）
• 用于动态自定义图标的 iconCss
• enabled、isVisible、isChecked 状态属性
• 用于分类逻辑的 groupBy
• 用于支持嵌套列表的 child 属性
• 验证模式和边缘情况

分组、嵌套列表与虚拟化

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

• 使用 groupTemplate 按类别对项进行分组
• 嵌套列表导航结构
• 使用 enableVirtualization 处理大型数据集
• 窗口滚动与容器滚动模式
• 在模板中进行条件渲染
• 性能优化策略

模板与自定义

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

• 用于自定义项的 template 属性
• headerTemplate 和 groupTemplate
• 内置 CSS 类（e-list-wrapper、e-list-avatar、e-list-badge 等）
• 头像和多行列表模式
• 模板中的自定义 HTML 标记

复选框、选择与事件

📄 阅读： references/checkboxes-selection-events.md

• showCheckBox 属性和位置（左侧/右侧）
• 携带 SelectEventArgs 的 select 事件
• 多项选择模式
• 已选中状态管理
• 选择事件处理

样式与外观

📄 阅读： references/styling-appearance-properties.md

• 用于自定义样式的 cssClass
• 高度和宽度控制
• showHeader 和 showIcon 属性
• 用于设置样式的 CSS 选择器参考
• 悬停和焦点状态自定义

事件与错误处理

📄 阅读： references/events-and-error-handling.md

• select、scroll、actionBegin、actionComplete 事件
• 在 TagHelper 中绑定事件
• 远程数据故障场景
• 错误处理策略

排序、筛选与滚动

📄 阅读： references/sorting-filtering-scrolling.md

• sortOrder 属性（Ascending、Descending）
• sortBy 字段映射
• 用于动态加载的 scroll 事件
• 无限滚动模式
• 筛选操作

无障碍与键盘导航

📄 阅读： references/accessibility-keyboard-aria.md

• 键盘快捷键（向上/向下箭头、选择、返回）
• ARIA 属性（aria-selected、aria-level）
• 使用 enableRtl 支持从右向左的布局
• 屏幕阅读器兼容性
• 包容性设计最佳实践

高级功能与持久化

📄 阅读： references/advanced-features-persistence.md

• 使用 enablePersistence 保留状态
• 搭配 AnimationSettings 使用 animation 属性
• 用于本地化的 locale
• disableHtmlEncode 和 enableHtmlSanitizer
• RTL 和文化适配

API 参考

📄 阅读： references/api-reference.md

• 完整的 ListView 属性列表（已记录 30 多个属性）
• 事件参考（select、scroll、actionBegin、actionComplete、actionFailure）
• 带类型签名的字段映射 API
• 枚举（SortOrder、AnimationEffect 等）
• 用于编程控制的方法签名
• 事件参数类型和属性

快速入门示例

使用 TagHelper 的基本 ASP.NET Core ListView：

@{
    ViewData["Title"] = "ListView Example";
    List<ListItem> dataSource = new List<ListItem>()
    {
        new ListItem { id = "1", text = "Artwork" },
        new ListItem { id = "2", text = "Abstract" },
        new ListItem { id = "3", text = "Modern Painting" },
        new ListItem { id = "4", text = "Ceramics" }
    };
}

<ejs-listview id="list" dataSource="dataSource" 
    showHeader="true" headerTitle="Art Gallery">
</ejs-listview>

@code {
    public class ListItem
    {
        public string id { get; set; }
        public string text { get; set; }
    }
}

包含选择和复选框：

<ejs-listview id="list" dataSource="dataSource" 
    showCheckBox="true" checkBoxPosition="Right">
</ejs-listview>

包含分组：

<ejs-listview id="list" dataSource="dataSource">
    <e-listview-fieldsettings text="text" groupBy="category" id="id"></e-listview-fieldsettings>
</ejs-listview>

常见模式

模式 1：简单数据列表

使用 dataSource 搭配字符串或对象数组；映射 fields.text 以显示文本。

模式 2：分类分组

设置 fields.groupBy，自动将项目整理到分类标题下。

模式 3：嵌套层级

映射 fields.child，启用父子关系间的逐层导航。

模式 4：大型数据集优化

启用 enableVirtualization="true"，仅渲染可见项目；性能可提升 10 倍以上。

模式 5：自定义项目显示

使用 template 属性搭配 <div class="e-list-wrapper"> 实现丰富的格式（头像、徽章、多行文本）。

模式 6：远程数据集成

将 dataSource 与 DataManager 搭配使用；设置 query 以在服务器端筛选/排序；绑定 fields 以匹配 API 响应。

关键字段映射参考

fields 属性用于控制数据提取。常见映射：

字段属性	用途	示例
text	项目的显示文本	text="productName"
id	唯一标识符	id="productId"
groupBy	分类/分组字段	groupBy="category"
child	嵌套列表数据	child="subcategories"
iconCss	图标类	iconCss="iconClass"
enabled	启用/禁用状态	enabled="isActive"
isChecked	复选框状态	isChecked="isSelected"
isVisible	可见性状态	isVisible="isVisible"
tooltip	悬停提示文本	tooltip="description"
sortBy	排序字段	sortBy="name"
htmlAttributes	自定义属性	htmlAttributes="attributes"

常见用例

用例 1：产品分类浏览器

按分类对产品分组；启用选择功能，以便将产品添加到购物车。

用例 2：文件/文件夹导航

使用带图标的嵌套列表构建文件浏览器界面。

用例 3：任务管理列表

将复选框与模板结合，用于待办/任务展示和状态跟踪。

用例 4：联系人目录

按字母顺序排序；使用包含头像和联系信息的模板；按分类筛选。

用例 5：大型数据流（新闻、日志）

启用虚拟化；实现滚动事件以动态加载；优化渲染。

---

后续步骤：

• 阅读 getting-started-and-data-binding.md，设置你的第一个 ListView
• 查看 api-reference.md，了解完整的属性、事件和方法文档
• 阅读 templates-and-customization.md，了解高级格式设置选项
• 查看 references/accessibility-keyboard-aria.md，了解键盘和 ARIA 支持