syncfusion-aspnetcore-multiselect

用途

本技能用于在 ASP.NET Core 应用程序中实现 Syncfusion 的 MultiSelect（多选下拉框）组件。MultiSelect 是一种高级下拉组件，允许用户从预定义列表中选取多个值，并具备过滤、模板、复选框、分组和完整的无障碍支持。该技能通过 Syncfusion 的标签助手（Tag Helper）语法指导完成实现。

适用时机

当你需要以下场景时可使用本技能：

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

主要能力

• 多选：从下拉列表中选取多个值
• 过滤与搜索：高效搜索大列表
• 复选框：以复选框模式提供多选的视觉提示
• 数据绑定：本地数组或远程数据源
• 模板：自定义项外观与已选值显示
• 分组：将选项组织为逻辑类别
• 排序：按字母升序/降序排列选项
• 标签显示：将已选项显示为可移除的 chip
• 自定义值：允许用户添加自定义选择值
• 虚拟滚动：高效处理 1000+ 项列表
• 级联：关联多个 MultiSelect 组件
• 无障碍合规：内置屏幕阅读器、键盘导航支持
• 事件：响应选择变化、打开、关闭等

文档导航

• 入门：前置条件与系统要求；安装 Syncfusion.EJ2.AspNet.Core NuGet 包；在 _ViewImports.cshtml 中配置 TagHelper；通过 CDN 添加样式表和脚本资源；注册脚本管理器；创建首个 MultiSelect；运行并测试应用。
• 标签助手语法：MultiSelect 标签助手结构与属性；基本属性（Placeholder、Value、Readonly、Disabled）；数据源绑定基础；标签助手中的事件绑定；CSS 类自定义；最佳实践与常见模式。
• 数据绑定：绑定字符串本地数组；绑定对象数组；带嵌套字段的复杂对象绑定；使用 DataManager 的远程数据源；字段映射（text、value、groupBy）；动态数据加载与刷新模式。
• 过滤与搜索：内置搜索框功能；过滤类型选项（contains、startswith、endswith）；使用服务端过滤的自定义过滤逻辑；用于高级搜索 UI 的过滤模板；NoRecordsTemplate 处理；搜索性能优化。
• 模板与自定义：项模板自定义；值模板（已选项显示）；页眉与页脚模板；分组页眉模板；项中的图标集成；CSS 样式与类自定义。
• 高级功能：增强多选 UI 的复选框模式；按类别分组项；排序选项（升序/降序）；自定义值支持（创建新值）；chip 自定义与移除；大数据集的虚拟滚动；级联 MultiSelect 模式。
• 无障碍：WCAG 2.2 AA 级合规；键盘导航（方向键、Tab、Enter、Escape）；ARIA 属性与角色；屏幕阅读器支持；焦点管理最佳实践；使用工具测试无障碍。

使用方式

快速上手示例：

在 _ViewImports.cshtml 中：

@addTagHelper *, Syncfusion.EJ2

视图文件中：

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

控制器中：

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();
}

常见模式：

• 简单字符串数组：使用 dataSource 绑定字符串列表。
• 对象数组带自定义显示：设置 fields-text 与 fields-value。
• 带复选框：设置 mode="CheckBox"。
• 带过滤的选择：设置 allowFiltering="true" 与 filterType="Contains"。

关键属性参考：

• 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）：按字段分组项

适用场景

• 管理后台角色选择：用户为管理员分配多个角色；显示全部可用角色；输入时过滤；将选择显示为 chip；校验选择数量。
• 产品分类过滤：电商网站按多个分类过滤产品；按父级分组分类；显示每个分类的项数；对 1000+ 项使用虚拟滚动；记住选择。
• 团队成员分配：将多个团队成员分配到项目；按姓名搜索；显示部门分组；在芯片中显示头像；防止自我分配。
• 标签选择：使用 MultiSelect 进行博客/内容打标签；允许创建自定义标签；显示标签计数/热度；按类别分组；自动完成建议。

最佳实践与限制

最佳实践：始终用关联的 <label> 元素标注 MultiSelect；适当预设合理的默认选择；列表超过 10 项时启用过滤；始终在服务端验证，不可仅依赖客户端验证；处理空状态；列表超过 20 项时使用 groupBy 分组；使用 maximumSelectionLength 限制选择数量；测试键盘导航；使用正确的 ARIA 属性提供无障碍标签；对 1000+ 项监控性能并使用虚拟滚动。

限制与缺失信息：官方资料未提供具体的价格、收费方案、性能指标或兼容的 .NET 版本范围，这些信息暂未提供。