syncfusion-aspnetcore-combobox

实现 Syncfusion ASP.NET Core ComboBox

组件概述

ComboBox 是一款功能强大的下拉控件，集成了以下功能：

• 便捷的选项选择，支持搜索和筛选
• 数据绑定支持，适用于本地数组和远程数据源
• 通过模板和样式实现丰富的自定义
• 支持分组、排序、虚拟滚动和级联等高级功能
• 内置无障碍功能，支持键盘导航和屏幕阅读器
• 通过 Tag Helper 语法与 ASP.NET Core 集成

主要功能：

• 输入提示/自动完成与筛选
• 自定义值（允许用户输入列表中不存在的数据）
• 数据分组和排序
• 用于列表项、页眉和页脚的下拉模板
• 使用 DataManager 进行远程数据绑定
• 面向大型数据集的虚拟滚动
• RTL（从右向左）支持
• 符合 WCAG 2.1 AA 标准

文档与导航指南

根据需要阅读以下参考资料：

入门

📄 阅读： references/getting-started.md

• 安装和 NuGet 包设置
• 在 ASP.NET Core 项目中添加 ComboBox
• 使用 Tag Helper 语法的最简可运行示例
• CSS/脚本导入和配置
• 运行你的第一个 ComboBox

数据绑定

📄 阅读： references/data-binding.md

• 绑定本地数组数据（字符串和对象）
• 使用 DataManager 绑定远程数据
• 映射复杂数据结构
• 自定义值支持
• OData 和 Web API 集成

筛选与搜索

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

• 启用自动完成和筛选
• 随用户输入进行搜索
• 更改筛选类型（contains、startsWith、endsWith）
• 区分大小写与不区分大小写的筛选
• 设置最小字符数阈值
• 从服务器进行远程筛选

模板与自定义

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

• 用于列表显示的项模板
• 页眉和页脚模板
• 分组标题自定义
• CSS 类自定义
• 使用 CSS 变量自定义主题
• 配置弹出窗口的高度/宽度

分组与排序

📄 阅读： references/grouping-and-sorting.md

• 按类别对项进行分组
• 按升序/降序排序
• 自定义排序函数
• 结合使用分组和排序
• 分组标题样式

自动填充与自动完成

📄 阅读： references/autofill-and-autocomplete.md

• 启用自动填充，加快数据录入
• 随用户输入自动完成
• 结合使用自动填充和筛选
• 建议项的键盘处理
• 大型数据集的性能

调整弹出窗口大小

📄 阅读： references/popup-resize.md

• 启用用户可调整大小的弹出窗口
• 设置初始宽度/高度
• 保留调整后的尺寸
• 自适应调整大小行为
• 调整大小手柄样式

高级功能

📄 阅读： references/advanced-features.md

• 创建级联 ComboBox
• 面向大型数据集的虚拟滚动
• 键盘导航（Tab、Enter、方向键）
• 无障碍属性（ARIA 标签）
• RTL（从右向左）支持
• 自定义验证
• 事件处理（change、selecting、select、filtering）

快速入门示例

以下是在 ASP.NET Core 中设置 ComboBox 的最简示例：

@{
    ViewData["Title"] = "ComboBox Example";
    List<string> sports = new List<string> { "Cricket", "Badminton", "Basketball", "Tennis" };
}

<ejs-combobox id="games" dataSource="@sports" placeholder="Select a sport"></ejs-combobox>

使用数据绑定：

@{
    var data = new List<object>
    {
        new { Id = 1, Text = "Microsoft", Code = "US" },
        new { Id = 2, Text = "Google", Code = "US" },
        new { Id = 3, Text = "Apple", Code = "US" }
    };
}

<ejs-combobox id="countries" 
              dataSource="@data" 
              fields-text="Text" 
              fields-value="Id"
              placeholder="Select a company">
</ejs-combobox>

操作指南

快速自动填充

使用自动填充，通过自动完成建议加快用户输入：

<ejs-combobox autofill="true" allowFiltering="true"></ejs-combobox>

可调整大小的弹出窗口

允许用户调整下拉弹出窗口的大小，以获得更好的可见性：

<ejs-combobox allowResize="true" popupWidth="400px" popupHeight="300px"></ejs-combobox>

常见模式

模式 1：筛选搜索 启用筛选功能，让用户在输入时进行搜索：

<ejs-combobox id="combobox" 
              dataSource="@data" 
              allowFiltering="true"
              placeholder="Type to search">
</ejs-combobox>

模式 2：级联 ComboBox 第二个 ComboBox 的数据取决于第一个 ComboBox 的选项。完整示例请参阅 advanced-features.md。

模式 3：自定义值输入 允许用户输入列表中不存在的值：

<ejs-combobox id="combobox" 
              allowCustom="true" 
              dataSource="@data">
</ejs-combobox>

模式 4：分组数据 按类别对项目分组：

<ejs-combobox id="combobox" 
              dataSource="@data" 
              fields-groupBy="Category"
              fields-text="Name">
</ejs-combobox>

关键属性

属性	类型	用途
dataSource	array or DataManager	下拉列表中显示的项目
fields-text	string	用作标签显示的字段
fields-value	string	用作选定值的字段
placeholder	string	内容为空时显示的提示文字
allowFiltering	bool	启用边输入边搜索/筛选
allowCustom	bool	允许用户输入列表中不存在的值
fields-groupBy	string	用于对项目分组的字段
sortOrder	Ascending/Descending	项目的排序方式
popupHeight	string	下拉列表的高度（例如 "300px"）
popupWidth	string	下拉列表的宽度
read-only	bool	禁止用户输入，只允许选择
enabled	bool	启用/禁用控件

常见用例

1. 从国家/城市列表中选择 → 使用数据绑定和可选的分组
2. 搜索大型数据集 → 使用筛选和虚拟滚动
3. 创建级联下拉列表 → 使用级联模式（参见高级功能）
4. 显示分类项目 → 使用分组和自定义模板
5. 匹配 API 响应数据 → 使用 DataManager 和字段映射
6. 构建无障碍表单 → 使用 ARIA 属性（参见高级功能）

---

后续步骤：

• 从 入门指南 开始安装和设置
• 前往 数据绑定 连接数据
• 探索 高级功能 以了解复杂场景

如有问题或需要排查故障，请查阅各参考文件中的注意事项和边缘情况。