syncfusion-blazor-multicolumn-combobox

实现 Syncfusion Blazor MultiColumn ComboBox

MultiColumn ComboBox 组件是一种下拉控件，可在多个列中显示数据，并内置筛选、选择、分页、虚拟化、分组和自定义等功能。它将传统 ComboBox 的功能与数据网格布局相结合。

何时使用此技能

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

• 在下拉列表中以多列显示结构化数据
• 实现跨列数据的筛选和搜索功能
• 绑定本地或远程数据源（Web API、OData）
• 支持采用灵活绑定选项的值选择
• 为大型数据集添加分页、虚拟化或分组
• 在表单中自定义外观、样式和验证
• 实现支持无障碍且可通过键盘导航的下拉列表
• 创建集成到服务端或 Web 应用中的 MultiColumn ComboBox 组件

组件概览

MultiColumn ComboBox 提供：

• 用于显示复杂数据结构的多列布局
• 高级筛选（本地/远程、区分大小写、多列）
• 数据绑定（本地数组、Web API、OData、自定义适配器）
• 值绑定的选择模式（简单值、元组、复杂对象）
• 性能功能（分页、虚拟化、离线模式）
• 自定义选项（模板、样式、外观）
• 集成表单验证和浮动标签
• 符合 WCAG 标准并支持键盘操作的无障碍功能

---

文档导航指南

入门

📄 阅读： references/getting-started.md

• 安装和包配置
• 基本的 MultiColumn ComboBox 实现
• 模板结构
• 创建第一个 MultiColumn ComboBox

列和数据显示

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

• 列的定义和配置
• 列模板和格式设置
• 列标题和文本对齐
• 网格设置（行高、交替行）

数据绑定选项

📄 阅读： references/data-binding.md

• 本地数据绑定（数组、集合）
• Web API 和 OData 绑定
• 操作事件（ActionBegin、ActionComplete、ActionFailure）
• 可观察集合和动态绑定

筛选和搜索

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

• 筛选类型和自定义筛选逻辑
• 多列筛选技术
• 区分大小写的筛选
• 远程数据筛选

选择和值绑定

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

• 单值和多值绑定
• 值选择模式
• 自定义值和枚举绑定
• 使用元组和复杂对象

高级功能和设置

📄 阅读： references/features-and-settings.md

• 用于提升性能的分页和虚拟化
• 按列对数据分组
• 弹出窗口设置（大小、位置、调整大小）
• 占位符和浮动标签

样式和外观

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

• CSS 类和自定义样式
• 占位符和浮动标签自定义
• 外观调整（交替行、网格线、文本换行）
• 主题集成

无障碍和本地化

📄 阅读： references/accessibility-localization.md

• 符合 WCAG 标准并支持键盘导航
• ARIA 属性和屏幕阅读器支持
• 表单验证集成
• 面向国际化应用的本地化

高级模式和集成

📄 阅读： references/advanced-patterns.md

• 服务端和 Web 应用集成
• 自定义数据适配器
• 枚举和动态对象绑定
• 离线模式和性能优化

快速入门示例

以下是一个最精简的 MultiColumn ComboBox 实现：

@using Syncfusion.Blazor.MultiColumnComboBox

<SfMultiColumnComboBox TValue="string" TItem="OrderData" 
                       DataSource="@OrderList" 
                       TextField="CustomerName"
                       ValueField="OrderID"
                       Placeholder="Select an order">
    <MultiColumnComboboxColumns>
        <MultiColumnComboboxColumn Field="OrderID" Header="Order ID" Width="100px"></MultiColumnComboboxColumn>
        <MultiColumnComboboxColumn Field="CustomerName" Header="Customer" Width="150px"></MultiColumnComboboxColumn>
        <MultiColumnComboboxColumn Field="TotalAmount" Header="Amount" Width="100px" Format="C2"></MultiColumnComboboxColumn>
    </MultiColumnComboboxColumns>
</SfMultiColumnComboBox>

@code {
    private List<OrderData> OrderList = new();

    protected override void OnInitialized()
    {
        OrderList = new()
        {
            new OrderData { OrderID = "1001", CustomerName = "Alice Johnson", TotalAmount = 150.50m },
            new OrderData { OrderID = "1002", CustomerName = "Bob Smith", TotalAmount = 280.75m },
            new OrderData { OrderID = "1003", CustomerName = "Carol White", TotalAmount = 420.00m }
        };
    }

    public class OrderData
    {
        public string OrderID { get; set; }
        public string CustomerName { get; set; }
        public decimal TotalAmount { get; set; }
    }
}

---

常见模式

1. 筛选用户输入

用户在搜索框中输入内容时，ComboBox 会筛选条目。使用 AllowFiltering 属性，并通过 FilterType 自定义筛选方式。

<SfMultiColumnComboBox TValue="string" TItem="ProductData" 
                       DataSource="@Products"
                       AllowFiltering="true"
                       FilterType="FilterType.Contains">
    <MultiColumnComboboxColumns>
        
    </MultiColumnComboboxColumns>
</SfMultiColumnComboBox>

2. 远程数据加载

使用数据适配器，通过 Query 属性绑定 Web API 或 OData 服务。

<SfMultiColumnComboBox TValue="string" TItem="OrderData"
                       Query="@DataQuery">
    <MultiColumnComboboxColumns>
        
    </MultiColumnComboboxColumns>
</SfMultiColumnComboBox>

@code {
    private Query DataQuery = new Query().From("Orders").Select(new List<string> { "OrderID", "CustomerName" });
}

3. 处理选择更改

使用 ValueChange 事件，在用户选择条目时作出响应。

<SfMultiColumnComboBox TValue="string" TItem="OrderData"
                       ValueChange="@OnValueChange">
    <MultiColumnComboboxColumns>
        
    </MultiColumnComboboxColumns>
</SfMultiColumnComboBox>

@code {
    private void OnValueChange(ValueChangeEventArgs<string, OrderData> args)
    {
        // args.Value = selected value
        // args.ItemData = selected item object
    }
}

4. 对大型数据集分页

启用分页以显示有限行数，并按需加载更多内容。

<SfMultiColumnComboBox TValue="string" TItem="OrderData"
                       AllowPaging="true"
                       PageSize="10">
    <MultiColumnComboboxColumns>
        
    </MultiColumnComboboxColumns>
</SfMultiColumnComboBox>

5. 表单验证

与 EditForm 集成，以进行验证和必填字段检查。

<EditForm Model="@FormModel">
    <SfMultiColumnComboBox TValue="string" TItem="OrderData"
                           @bind-Value="@FormModel.SelectedOrderID"
                           DataSource="@Orders">
        <MultiColumnComboboxColumns>
            
        </MultiColumnComboboxColumns>
    </SfMultiColumnComboBox>
    
    <ValidationMessage For="@(() => FormModel.SelectedOrderID)" />
</EditForm>

---

关键属性

TextField| 映射显示文本字段 |TextField="Name"| |ValueField| 映射值字段 |ValueField="ID"` |

属性	说明	示例
DataSource	要绑定的数据集合	DataSource="@Products"
TextField	映射显示文本字段	TextField="Name"
ValueField	映射值字段	ValueField="ID"
Value / @bind-Value	获取/设置选中的值	@bind-Value="@SelectedID"
AllowFiltering	启用搜索/筛选功能	AllowFiltering="true"
FilterType	筛选匹配方式	FilterType="FilterType.Contains"
Placeholder	输入提示文本	Placeholder="Select..."
AllowPaging	启用分页	AllowPaging="true"
PageSize	每页条目数（启用分页时）	PageSize="10"
GroupByField	按字段对条目分组	GroupByField="Category"
Query	用于远程数据源的数据查询	Query="@new Query().From('Orders')"
Disabled / ReadOnly	控件状态	`Dis

---

常见用例

1. 订单选择表单 - 用户可在类似网格的下拉列表中选择订单，查看订单 ID、客户和金额
2. 员工查找 - 跨多列按姓名、电子邮件或 ID 搜索员工
3. 产品目录 - 在多列下拉列表中显示产品的类别、价格和库存
4. 位置选择器 - 选择城市/地区，并查看国家、州和时区信息
5. 账户选择 - 在一个下拉列表中选择账户，并查看账号、类型和余额

---

接下来做什么？

从 入门指南 开始，安装并创建你的第一个 MultiColumn ComboBox，然后根据需要探索其他指南。每份参考指南都提供完整的代码示例和边缘情况说明。

有问题？ 请查看与你的具体用例相关的参考指南。