syncfusion-aspnetcore-multiselect

在 ASP.NET Core 中实现 MultiSelect

MultiSelect 是一种高级下拉组件，可让用户从预定义列表中选择多个值，并提供筛选、模板、复选框、分组和完整的无障碍支持等功能。本技能将指导你使用 Syncfusion 的标记帮助程序语法，在 ASP.NET Core 应用程序中实现 MultiSelect。

何时使用此技能

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

• 创建用户可选择多个选项的下拉字段
• 为大型选项列表添加搜索／筛选功能
• 将选中项显示为可移除的标签
• 使用复选框实现清晰的多选界面
• 绑定到本地数组或远程数据源
• 使用模板自定义列表项外观
• 按类别对相关选项分组
• 确保符合 WCAG 2.2 无障碍标准
• 处理复杂的选择场景（级联、自定义值）

主要功能

功能	使用场景
多选	从下拉列表中选择多个值
筛选与搜索	高效搜索大型列表
复选框	使用复选框模式直观显示多选状态
数据绑定	本地数组或远程数据源
模板	自定义项的外观和选中值的显示方式
分组	按逻辑类别组织选项
排序	按字母顺序对选项进行排序（升序／降序）
标签显示	将选中项显示为可移除的标签
自定义值	允许用户添加自定义选项值
虚拟滚动	高效处理包含 1000+ 项的列表
级联	关联多个 MultiSelect 组件
WCAG 合规性	内置无障碍功能，支持屏幕阅读器和键盘导航
事件	响应选择更改、打开和关闭事件

文档导航指南

入门

📄 阅读： references/getting-started.md

• 先决条件和系统要求
• 安装 Syncfusion.EJ2.AspNet.Core NuGet 包
• 在 _ViewImports.cshtml 中配置 TagHelper
• 通过 CDN 添加样式表和脚本资源
• 注册脚本管理器
• 创建第一个 MultiSelect
• 运行并测试应用程序

Tag Helper 语法

📄 阅读： references/tag-helper-syntax.md

• MultiSelect 标记帮助程序的结构和属性
• 基本属性（Placeholder、Value、Readonly、Disabled）
• 数据源绑定基础知识
• 在标记帮助程序中绑定事件
• 自定义 CSS 类
• 最佳实践和常见模式

数据绑定

📄 阅读： references/data-binding.md

• 绑定到字符串本地数组
• 绑定到对象数组
• 使用嵌套字段绑定复杂对象
• 使用 DataManager 连接远程数据源
• 字段映射（text、value、groupBy）
• 动态加载数据和刷新模式

筛选和搜索

📄 阅读： references/filtering-and-search.md

• 内置搜索框功能
• 筛选类型选项（contains、startswith、endswith）
• 使用服务器端筛选实现自定义筛选逻辑
• 用于高级搜索界面的筛选模板
• NoRecordsTemplate 处理
• 搜索性能优化

模板和自定义

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

• 自定义项模板
• 值模板（选中项显示）
• 页眉和页脚模板
• 分组标题模板
• 在项中集成图标
• CSS 样式和类自定义

高级功能

📄 阅读： references/advanced-features.md

• 用于增强多选界面的复选框模式
• 按类别对项分组
• 排序选项（升序／降序）
• 支持自定义值（创建新值）
• 标签自定义和移除
• 用于大型数据集的虚拟滚动
• 级联 MultiSelect 模式

无障碍访问

📄 阅读： references/accessibility.md

• 符合 WCAG 2.2 AA 级标准
• 键盘导航（方向键、Tab、Enter、Escape）
• ARIA 属性和角色
• 屏幕阅读器支持
• 焦点管理最佳实践
• 使用工具测试无障碍访问

快速入门示例

以下是一个最简 MultiSelect 实现：

@addTagHelper *, Syncfusion.EJ2


<ejs-multiselect id="multiselect" 
    dataSource="ViewBag.DataSource" 
    fields-text="Name" 
    fields-value="Id"
    placeholder="Select options">
</ejs-multiselect>

// Controller
public IActionResult Index()
{
    List<SelectData> data = new List<SelectData>
    {
        new SelectData { Id = "1", Name = "Option 1" },
        new SelectData { Id = "2", Name = "Option 2" },
        new SelectData { Id = "3", Name = "Option 3" }
    };
    ViewBag.DataSource = data;
    return View();
}

常见模式

模式 1：简单字符串数组

从字符串值列表中进行选择：

<ejs-multiselect id="skills" 
    dataSource="ViewBag.SkillsList" 
    placeholder="Select skills">
</ejs-multiselect>

模式 2：带自定义显示的对象数组

<ejs-multiselect id="products" 
    dataSource="ViewBag.ProductList"
    fields-text="ProductName"
    fields-value="ProductId"
    placeholder="Select products">
</ejs-multiselect>

模式 3：带复选框

<ejs-multiselect id="languages" 
    dataSource="ViewBag.LanguageList"
    fields-text="Language"
    fields-value="LanguageCode"
    mode="CheckBox"
    placeholder="Select languages">
</ejs-multiselect>

模式 4：筛选选择

<ejs-multiselect id="countries" 
    dataSource="ViewBag.CountryList"
    fields-text="CountryName"
    fields-value="CountryCode"
    allowFiltering="true"
    filterType="Contains"
    placeholder="Search and select countries">
</ejs-multiselect>

关键属性参考

属性	类型	描述
dataSource	Array	数据项列表
fields-text	string	用于显示文本的字段名称
fields-value	string	用于数据值的字段名称
placeholder	string	内容为空时显示的提示文本
value	string[]	初始选中的值
allowFiltering	boolean	启用搜索/筛选框
filterType	string	筛选类型（StartsWith、Contains、EndsWith）
mode	string	选择模式（Default、CheckBox、Delimiter）
readonly	boolean	禁止编辑
disabled	boolean	禁用控件
showSelectAll	boolean	显示“全选”复选框
maximumSelectionLength	number	可选项的最大数量
delayUpdateOn	string	触发更新的事件
fields-groupBy	string	按字段对项目分组

常见用例

用例 1：管理面板中的角色选择

用户选择多个角色并分配给管理员：

• 显示所有可用角色
• 随着用户输入进行筛选
• 将选中项显示为标签
• 验证选中项数量

用例 2：商品类别筛选

电商网站按多个类别筛选商品：

• 按父类别对类别分组
• 显示每个类别的项目数量
• 对 1000 项以上的数据使用虚拟滚动
• 记住选择

用例 3：团队成员分配

为项目分配多名团队成员：

• 按姓名搜索
• 显示部门分组
• 在选中项标签中显示头像
• 防止分配给自己

用例 4：标签选择

使用 MultiSelect 为博客/内容添加标签：

• 允许创建自定义标签
• 显示标签数量/热度
• 按类别分组
• 自动补全建议

最佳实践

1. 始终提供清晰的标签 - 使用关联的 <label> 元素为 MultiSelect 添加标签
2. 设置合理的默认选项 - 在适当情况下预先选中符合逻辑的默认项
3. 为长列表启用筛选 - 项目超过 10 个时启用筛选
4. 在服务端进行验证 - 切勿只依赖客户端验证
5. 处理空状态 - 未选中任何项目时提供清晰的提示
6. 对相关项目进行分组 - 列表超过 20 项时使用 groupBy
7. 限制选中数量 - 使用 maximumSelectionLength 防止滥用
8. 测试键盘导航 - 确保所有功能都可通过键盘访问
9. 提供无障碍标签 - 使用恰当的 ARIA 属性
10. 监控性能 - 对 1000 项以上的数据使用虚拟滚动

后续步骤

1. 从入门指南开始 - 按照设置说明操作
2. 实现一个简单示例 - 创建基本的 MultiSelect 绑定
3. 添加筛选 - 启用搜索功能
4. 自定义模板 - 使用模板优化外观
5. 处理选择事件 - 响应用户选择
6. 测试无障碍访问 - 验证键盘和屏幕阅读器支持

---

准备好开始学习了吗？ 从入门指南开始 →