syncfusion-blazor-multicolumn-combobox

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Implementing Syncfusion Blazor MultiColumn ComboBox

Syncfusion Blazor MultiColumn ComboBox 实现指南

The MultiColumn ComboBox component is a dropdown control that displays data in multiple columns with built-in features like filtering, selection, paging, virtualization, grouping, and customization. It combines the capabilities of a traditional ComboBox with a data grid layout.

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

When to Use This Skill

何时使用该组件

Use this skill when you need to:

Display structured data in a dropdown with multiple columns
Implement filtering and search capabilities across column data
Bind to local or remote data sources (Web API, OData)
Support value selection with flexible binding options
Add paging, virtualization, or grouping to large datasets
Customize appearance, styling, and validation in forms
Implement accessible, keyboard-navigable dropdowns
Create server-side or web app integrated MultiColumn ComboBox components

当你需要以下功能时，可使用该组件：

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

Component Overview

组件概述

The MultiColumn ComboBox provides:

Multi-column layout for displaying complex data structures
Advanced filtering (local/remote, case-sensitive, multi-column)
Data binding (local arrays, Web API, OData, custom adaptors)
Selection modes with value binding (simple, tuple, complex objects)
Performance features (paging, virtualization, offline mode)
Customization (templates, styling, appearance)
Form integration with validation and floating labels
Accessibility with WCAG compliance and keyboard support

MultiColumn ComboBox提供以下功能：

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

Documentation Navigation Guide

文档导航指南

Getting Started

快速入门

📄 Read: references/getting-started.md

Installation and package setup
Basic MultiColumn ComboBox implementation
Template structure
Creating your first MultiColumn ComboBox

📄 阅读： references/getting-started.md

安装与包配置
MultiColumn ComboBox基础实现
模板结构
创建你的第一个MultiColumn ComboBox

Columns and Data Display

列与数据展示

📄 Read: references/columns-and-templates.md

Column definition and configuration
Column templates and formatting
Column headers and text alignment
Grid settings (row height, alternating rows)

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

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

Data Binding Options

数据绑定选项

📄 Read: references/data-binding.md

Local data binding (arrays, collections)
Web API and OData binding
Action events (ActionBegin, ActionComplete, ActionFailure)
Observable collections and dynamic binding

📄 阅读： references/data-binding.md

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

Filtering and Search

筛选与搜索

📄 Read: references/filtering-and-search.md

Filter types and custom filtering logic
Multi-column filtering techniques
Case-sensitive filtering
Remote data filtering

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

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

Selection and Value Binding

选择与值绑定

📄 Read: references/selection-and-values.md

Single and multiple value binding
Value selection patterns
Custom values and enum binding
Working with tuples and complex objects

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

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

Advanced Features and Settings

高级特性与设置

📄 Read: references/features-and-settings.md

Paging and virtualization for performance
Grouping data by columns
Popup settings (size, position, resize)
Placeholder and floating labels

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

用于性能优化的分页与虚拟化
按列分组数据
弹出框设置（尺寸、位置、调整大小）
占位符与浮动标签

Styling and Appearance

样式与外观

📄 Read: references/styling-and-appearance.md

CSS classes and custom styling
Placeholder and float label customization
Appearance tweaks (alt rows, grid lines, text wrapping)
Theme integration

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

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

Accessibility and Localization

可访问性与本地化

📄 Read: references/accessibility-localization.md

WCAG compliance and keyboard navigation
ARIA attributes and screen reader support
Form validation integration
Localization for international apps

📄 阅读： references/accessibility-localization.md

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

Advanced Patterns and Integration

高级模式与集成

📄 Read: references/advanced-patterns.md

Server-side and web app integration
Custom data adaptors
Enum and dynamic object binding
Offline mode and performance optimization

📄 阅读： references/advanced-patterns.md

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

Quick Start Example

快速入门示例

Here's a minimal MultiColumn ComboBox implementation:

razor

@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; }
    }
}

以下是MultiColumn ComboBox的最简实现：

razor

@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; }
    }
}

Common Patterns

常用模式

1. Filtering User Input

1. 用户输入筛选

When users type in the search box, the ComboBox filters items. Use the

AllowFiltering

property and customize with

FilterType

razor

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

当用户在搜索框中输入内容时，ComboBox会筛选项目。使用

AllowFiltering

属性并通过

FilterType

自定义筛选方式。

razor

<SfMultiColumnComboBox TValue="string" TItem="ProductData" 
                       DataSource="@Products"
                       AllowFiltering="true"
                       FilterType="FilterType.Contains">
    <MultiColumnComboboxColumns>
        <!-- 列定义 -->
    </MultiColumnComboboxColumns>
</SfMultiColumnComboBox>

2. Remote Data Loading

2. 远程数据加载

Bind to Web API or OData services using the

Query

property with data adaptor.

razor

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

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

使用

Query

属性结合数据适配器绑定到Web API或OData服务。

razor

<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. Handling Selection Change

3. 处理选择变更

Use the

ValueChange

event to respond when user selects an item.

razor

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

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

使用

ValueChange

响应用户选择项目的事件。

razor

<SfMultiColumnComboBox TValue="string" TItem="OrderData"
                       ValueChange="@OnValueChange">
    <MultiColumnComboboxColumns>
        <!-- 列定义 -->
    </MultiColumnComboboxColumns>
</SfMultiColumnComboBox>

@code {
    private void OnValueChange(ValueChangeEventArgs<string, OrderData> args)
    {
        // args.Value = 选中的值
        // args.ItemData = 选中的项目对象
    }
}

4. Paging Large Datasets

4. 大型数据集分页

Enable paging to show limited rows and load more on demand.

razor

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

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

razor

<SfMultiColumnComboBox TValue="string" TItem="OrderData"
                       AllowPaging="true"
                       PageSize="10">
    <MultiColumnComboboxColumns>
        <!-- 列定义 -->
    </MultiColumnComboboxColumns>
</SfMultiColumnComboBox>

5. Form Validation

5. 表单验证

Integrate with EditForm for validation and required field checks.

razor

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

与EditForm集成以实现验证和必填字段检查。

razor

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

Key Properties

关键属性

TextField

| Maps display text field |

TextField="Name"

| |

ValueField

| Maps value field |

ValueField="ID"` |

Property	Description	Example
`DataSource`	Data collection to bind	`DataSource="@Products"`
`TextField`	Maps display text field	`TextField="Name"`
`ValueField`	Maps value field	`ValueField="ID"`
`Value` / `@bind-Value`	Gets/sets selected value	`@bind-Value="@SelectedID"`
`AllowFiltering`	Enables search/filter capability	`AllowFiltering="true"`
`FilterType`	Filter matching behavior	`FilterType="FilterType.Contains"`
`Placeholder`	Input hint text	`Placeholder="Select..."`
`AllowPaging`	Enables paging	`AllowPaging="true"`
`PageSize`	Items per page (with paging)	`PageSize="10"`
`GroupByField`	Groups items by field	`GroupByField="Category"`
`Query`	Data query for remote sources	`Query="@new Query().From('Orders')"`
`Disabled` / `ReadOnly`	Control states	`Dis

属性	描述	示例
`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`	控件状态	`Disabled` / `ReadOnly="true"`

Common Use Cases

常见使用场景

Order Selection Form - Users pick orders from a grid-like dropdown with order ID, customer, and amount
Employee Lookup - Search employees by name, email, or ID across multiple columns
Product Catalog - Display products with category, price, and stock in a multi-column dropdown
Location Selector - Select cities/regions with country, state, and timezone information
Account Selection - Pick from accounts showing number, type, and balance in one dropdown

订单选择表单 - 用户从类网格的下拉菜单中选择包含订单ID、客户和金额的订单
员工查找 - 通过姓名、邮箱或ID在多列中搜索员工
产品目录 - 在多列下拉菜单中显示包含分类、价格和库存的产品
位置选择器 - 选择包含国家、州和时区信息的城市/地区
账户选择 - 在单个下拉菜单中选择包含账号、类型和余额的账户

What's Next?

下一步

Start with Getting Started to install and create your first MultiColumn ComboBox, then explore other guides based on your needs. Each reference provides complete code examples and edge cases.

Questions? Check the relevant reference guide for your specific use case.

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

有疑问？ 针对你的具体使用场景查看相关参考指南。