Back to Details

syncfusion-winforms-multicolumn-combobox

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Implementing Multi-Column ComboBoxes (MultiColumnComboBox)

实现多列组合框（MultiColumnComboBox）

An advanced combobox control for Windows Forms that displays multiple columns in the dropdown list with virtual data binding support for instantaneous loading of large datasets.
这是一款适用于Windows Forms的高级组合框控件，下拉列表可展示多列内容，支持虚拟数据绑定，可瞬时加载大型数据集。

When to Use This Skill

何时使用本技能

Use this skill when you need to:
  • Multi-Column Dropdowns: Display multiple data fields in dropdown (like DataGridView in dropdown)
  • Large Dataset Binding: Bind to large datasources with virtual rendering for performance
  • Data Lookup: Show related fields (ID, Name, Description, Category) in dropdown
  • Entity Selection: Select records with multiple visible properties
  • Filtered Dropdowns: Apply custom filtering across all columns
  • Styled Comboboxes: Apply Office themes (2003-2019) to dropdown controls
  • DataSource Binding: Use DataSource, DisplayMember, and ValueMember properties
  • ComboBox Replacement: Replace standard ComboBox with richer multi-column display
当你需要实现以下需求时可使用本技能：
  • 多列下拉：在下拉菜单中展示多个数据字段（类似下拉菜单中的DataGridView）
  • 大型数据集绑定：绑定大型数据源时通过虚拟渲染保证性能
  • 数据查找：在下拉菜单中展示关联字段（ID、名称、描述、分类）
  • 实体选择：选择带有多个可见属性的记录
  • 过滤下拉：对所有列应用自定义过滤规则
  • 样式化组合框：为下拉控件应用Office主题（2003-2019）
  • DataSource绑定：使用DataSource、DisplayMember和ValueMember属性
  • ComboBox替换：用更丰富的多列展示替换标准ComboBox

Component Overview

组件概述

The MultiColumnComboBox is based on ComboBoxBase and provides:
  • Multiple columns in dropdown list
  • Virtual data binding for large datasets (instantaneous loading)
  • Automatic display of all fields in datasource
  • DataSource, DisplayMember, and ValueMember properties
  • Column headers with ShowColumnHeader property
  • Custom filtering across all columns
  • Grid-based dropdown (GridListControl)
  • Cannot manually add items (data binding only)
Key Capabilities:
  • DataSource
    property for binding data (DataTable, DataView, DataSet, List<T>)
  • DisplayMember
    and 
    ValueMember
    for column selection
  • ShowColumnHeader
    property for displaying column headers
  • AllowFiltering
    property for enabling custom filtering
  • Style
    property for applying Office visual themes
  • AlphaBlendSelectionColor
    for customizing selection appearance
  • DropDownWidth
    for controlling dropdown width
MultiColumnComboBox 基于ComboBoxBase开发，提供以下能力：
  • 下拉列表支持多列展示
  • 面向大型数据集的虚拟数据绑定（瞬时加载）
  • 自动展示数据源中的所有字段
  • 支持DataSource、DisplayMember和ValueMember属性
  • 可通过ShowColumnHeader属性控制是否展示列头
  • 支持跨所有列的自定义过滤
  • 基于网格的下拉菜单（GridListControl）
  • 不支持手动添加条目（仅支持数据绑定）
核心能力：
  • 用于绑定数据的
    DataSource
    属性（支持DataTable、DataView、DataSet、List<T>）
  • 用于选择列的
    DisplayMember
    和
    ValueMember
    属性
  • 用于展示列头的
    ShowColumnHeader
    属性
  • 用于启用自定义过滤的
    AllowFiltering
    属性
  • 用于应用Office视觉主题的
    Style
    属性
  • 用于自定义选中样式的
    AlphaBlendSelectionColor
    属性
  • 用于控制下拉宽度的
    DropDownWidth
    属性

Documentation and Navigation Guide

文档与导航指南

Getting Started

入门指南

📄 Read: references/getting-started.md
When to read: Starting new implementation, first-time setup, basic control creation
Topics covered:
  • Assembly and namespace requirements (Syncfusion.Windows.Forms.Tools)
  • Adding via designer (drag-and-drop from toolbox)
  • Adding via code (programmatic creation)
  • Basic MultiColumnComboBox instantiation
  • Form integration
  • Initial setup steps
📄 阅读： references/getting-started.md
适用场景： 启动新实现、首次配置、基础控件创建
覆盖主题：
  • 程序集与命名空间要求（Syncfusion.Windows.Forms.Tools）
  • 通过设计器添加（从工具箱拖拽）
  • 通过代码添加（编程式创建）
  • 基础MultiColumnComboBox实例化
  • 表单集成
  • 初始配置步骤

Data Binding

数据绑定

📄 Read: references/data-binding.md
When to read: Binding to datasources, configuring DataSource/DisplayMember/ValueMember, loading data from databases or XML
Topics covered:
  • DataSource, DisplayMember, ValueMember properties
  • DataView as datasource
  • OleDBDataAdapter usage with databases
  • Typed DataSet population
  • XML data loading (ReadXml)
  • Hiding specific columns (Grid.Model.Cols.Hidden)
  • Accessing DataRowView for selected items
  • Complete data binding examples
📄 阅读： references/data-binding.md
适用场景： 绑定数据源、配置DataSource/DisplayMember/ValueMember、从数据库或XML加载数据
覆盖主题：
  • DataSource、DisplayMember、ValueMember属性
  • 使用DataView作为数据源
  • OleDBDataAdapter对接数据库的用法
  • 类型化DataSet填充
  • XML数据加载（ReadXml）
  • 隐藏指定列（Grid.Model.Cols.Hidden）
  • 访问选中条目的DataRowView
  • 完整数据绑定示例

Multiple Columns Configuration

多列配置

📄 Read: references/multiple-columns.md
When to read: Configuring columns, enabling/disabling multi-column mode, filtering, dropdown width
Topics covered:
  • MultiColumn property (enable/disable columns)
  • ShowColumnHeader property (display column headers)
  • AlphaBlendSelectionColor (selection highlight color)
  • DropDownWidth property (dropdown width configuration)
  • AllowFiltering property (enable custom filtering)
  • Filter property (predicate-based filtering)
  • Custom filter implementation
  • Default filtering behavior (StartsWith on DisplayMember)
📄 阅读： references/multiple-columns.md
适用场景： 配置列、启用/禁用多列模式、过滤、下拉宽度配置
覆盖主题：
  • MultiColumn属性（启用/禁用多列）
  • ShowColumnHeader属性（展示列头）
  • AlphaBlendSelectionColor（选中高亮颜色）
  • DropDownWidth属性（下拉宽度配置）
  • AllowFiltering属性（启用自定义过滤）
  • Filter属性（基于谓词的过滤）
  • 自定义过滤器实现
  • 默认过滤行为（对DisplayMember执行开头匹配）

Appearance and Styling

外观与样式

📄 Read: references/appearance-styling.md
When to read: Applying visual themes, customizing appearance, Office theme configuration
Topics covered:
  • Style property (9 visual styles)
  • Office2003, OfficeXP, VS2005 styles
  • Office2007 with color schemes (Blue, Silver, Black)
  • Metro, Office2016 variants (Colorful, White, Black, DarkGray)
  • Office2007ColorTheme property
  • Custom colors with ApplyManagedColors method
  • Managed theme configuration
  • Complete styling examples
📄 阅读： references/appearance-styling.md
适用场景： 应用视觉主题、自定义外观、Office主题配置
覆盖主题：
  • Style属性（9种视觉样式）
  • Office2003、OfficeXP、VS2005样式
  • 带配色方案的Office2007（蓝色、银色、黑色）
  • Metro、Office2016变体（多彩、白色、黑色、深灰）
  • Office2007ColorTheme属性
  • 使用ApplyManagedColors方法自定义颜色
  • 托管主题配置
  • 完整样式示例

Event Handling

事件处理

📄 Read: references/event-handling.md
When to read: Handling selection changes, responding to user interactions, accessing selected data
Topics covered:
  • SelectionChangedCommitted event
  • SelectedValueChanged event
  • SelectedIndexChanged event
  • Event occurrence scenarios and order
  • Accessing selected item data (DataRowView)
  • Setting text based on selection
  • Complete event handler examples
📄 阅读： references/event-handling.md
适用场景： 处理选中变更、响应用户交互、访问选中数据
覆盖主题：
  • SelectionChangedCommitted事件
  • SelectedValueChanged事件
  • SelectedIndexChanged事件
  • 事件触发场景与顺序
  • 访问选中条目数据（DataRowView）
  • 根据选中内容设置文本
  • 完整事件处理示例

Quick Start Example

快速入门示例

Multi-Column Employee Selector with Data Binding

带数据绑定的多列员工选择器

csharp
using Syncfusion.Windows.Forms.Tools;
using System.Data;

// Create DataTable with employee data
DataTable employeeData = new DataTable("Employees");
employeeData.Columns.Add("EmployeeID");
employeeData.Columns.Add("FirstName");
employeeData.Columns.Add("LastName");
employeeData.Columns.Add("Department");
employeeData.Columns.Add("Position");

// Add sample data
employeeData.Rows.Add("1001", "John", "Smith", "Engineering", "Developer");
employeeData.Rows.Add("1002", "Mary", "Johnson", "Sales", "Manager");
employeeData.Rows.Add("1003", "Robert", "Williams", "HR", "Specialist");
employeeData.Rows.Add("1004", "Sarah", "Davis", "Marketing", "Coordinator");

// Create and configure MultiColumnComboBox
MultiColumnComboBox employeeCombo = new MultiColumnComboBox();
employeeCombo.Location = new Point(20, 20);
employeeCombo.Size = new Size(300, 21);

// Bind data
employeeCombo.DataSource = employeeData;
employeeCombo.DisplayMember = "FirstName";
employeeCombo.ValueMember = "EmployeeID";

// Configure appearance
employeeCombo.ShowColumnHeader = true;
employeeCombo.Style = VisualStyle.Office2016Colorful;
employeeCombo.DropDownWidth = 500;

// Add to form
this.Controls.Add(employeeCombo);
vbnet
Imports Syncfusion.Windows.Forms.Tools
Imports System.Data

' Create DataTable with employee data
Dim employeeData As New DataTable("Employees")
employeeData.Columns.Add("EmployeeID")
employeeData.Columns.Add("FirstName")
employeeData.Columns.Add("LastName")
employeeData.Columns.Add("Department")
employeeData.Columns.Add("Position")

' Add sample data
employeeData.Rows.Add("1001", "John", "Smith", "Engineering", "Developer")
employeeData.Rows.Add("1002", "Mary", "Johnson", "Sales", "Manager")
employeeData.Rows.Add("1003", "Robert", "Williams", "HR", "Specialist")
employeeData.Rows.Add("1004", "Sarah", "Davis", "Marketing", "Coordinator")

' Create and configure MultiColumnComboBox
Dim employeeCombo As New MultiColumnComboBox()
employeeCombo.Location = New Point(20, 20)
employeeCombo.Size = New Size(300, 21)

' Bind data
employeeCombo.DataSource = employeeData
employeeCombo.DisplayMember = "FirstName"
employeeCombo.ValueMember = "EmployeeID"

' Configure appearance
employeeCombo.ShowColumnHeader = True
employeeCombo.Style = VisualStyle.Office2016Colorful
employeeCombo.DropDownWidth = 500

' Add to form
Me.Controls.Add(employeeCombo)
csharp
using Syncfusion.Windows.Forms.Tools;
using System.Data;

// Create DataTable with employee data
DataTable employeeData = new DataTable("Employees");
employeeData.Columns.Add("EmployeeID");
employeeData.Columns.Add("FirstName");
employeeData.Columns.Add("LastName");
employeeData.Columns.Add("Department");
employeeData.Columns.Add("Position");

// Add sample data
employeeData.Rows.Add("1001", "John", "Smith", "Engineering", "Developer");
employeeData.Rows.Add("1002", "Mary", "Johnson", "Sales", "Manager");
employeeData.Rows.Add("1003", "Robert", "Williams", "HR", "Specialist");
employeeData.Rows.Add("1004", "Sarah", "Davis", "Marketing", "Coordinator");

// Create and configure MultiColumnComboBox
MultiColumnComboBox employeeCombo = new MultiColumnComboBox();
employeeCombo.Location = new Point(20, 20);
employeeCombo.Size = new Size(300, 21);

// Bind data
employeeCombo.DataSource = employeeData;
employeeCombo.DisplayMember = "FirstName";
employeeCombo.ValueMember = "EmployeeID";

// Configure appearance
employeeCombo.ShowColumnHeader = true;
employeeCombo.Style = VisualStyle.Office2016Colorful;
employeeCombo.DropDownWidth = 500;

// Add to form
this.Controls.Add(employeeCombo);
vbnet
Imports Syncfusion.Windows.Forms.Tools
Imports System.Data

' Create DataTable with employee data
Dim employeeData As New DataTable("Employees")
employeeData.Columns.Add("EmployeeID")
employeeData.Columns.Add("FirstName")
employeeData.Columns.Add("LastName")
employeeData.Columns.Add("Department")
employeeData.Columns.Add("Position")

' Add sample data
employeeData.Rows.Add("1001", "John", "Smith", "Engineering", "Developer")
employeeData.Rows.Add("1002", "Mary", "Johnson", "Sales", "Manager")
employeeData.Rows.Add("1003", "Robert", "Williams", "HR", "Specialist")
employeeData.Rows.Add("1004", "Sarah", "Davis", "Marketing", "Coordinator")

' Create and configure MultiColumnComboBox
Dim employeeCombo As New MultiColumnComboBox()
employeeCombo.Location = New Point(20, 20)
employeeCombo.Size = New Size(300, 21)

' Bind data
employeeCombo.DataSource = employeeData
employeeCombo.DisplayMember = "FirstName"
employeeCombo.ValueMember = "EmployeeID"

' Configure appearance
employeeCombo.ShowColumnHeader = True
employeeCombo.Style = VisualStyle.Office2016Colorful
employeeCombo.DropDownWidth = 500

' Add to form
Me.Controls.Add(employeeCombo)

Common Patterns

常见模式

Pattern 1: Database Lookup with OleDbDataAdapter

模式1：使用OleDbDataAdapter实现数据库查找

csharp
using System.Data.OleDb;

// Create data adapter and dataset
OleDbDataAdapter adapter = new OleDbDataAdapter(
    "SELECT CustomerID, CompanyName, ContactName, Country FROM Customers", 
    connectionString);
DataSet dataSet = new DataSet();
adapter.Fill(dataSet, "Customers");

// Bind to MultiColumnComboBox
multiColumnComboBox1.DataSource = dataSet.Tables["Customers"];
multiColumnComboBox1.DisplayMember = "CompanyName";
multiColumnComboBox1.ValueMember = "CustomerID";
multiColumnComboBox1.ShowColumnHeader = true;
multiColumnComboBox1.DropDownWidth = 600;
csharp
using System.Data.OleDb;

// Create data adapter and dataset
OleDbDataAdapter adapter = new OleDbDataAdapter(
    "SELECT CustomerID, CompanyName, ContactName, Country FROM Customers", 
    connectionString);
DataSet dataSet = new DataSet();
adapter.Fill(dataSet, "Customers");

// Bind to MultiColumnComboBox
multiColumnComboBox1.DataSource = dataSet.Tables["Customers"];
multiColumnComboBox1.DisplayMember = "CompanyName";
multiColumnComboBox1.ValueMember = "CustomerID";
multiColumnComboBox1.ShowColumnHeader = true;
multiColumnComboBox1.DropDownWidth = 600;

Pattern 2: Custom Filtering by Any Column

模式2：按任意列自定义过滤

csharp
// Enable filtering
multiColumnComboBox1.AllowFiltering = true;

// Handle text changed for custom filter
multiColumnComboBox1.TextChanged += (sender, e) =>
{
    multiColumnComboBox1.Filter = FilterRecords;
};

// Custom filter predicate
private bool FilterRecords(object o)
{
    var item = o as DataRowView;
    if (item != null)
    {
        string searchText = multiColumnComboBox1.TextBox.Text.ToLower();
        
        // Filter by any column
        return item["ProductName"].ToString().ToLower().Contains(searchText) ||
               item["Category"].ToString().ToLower().Contains(searchText);
    }
    return false;
}
csharp
// Enable filtering
multiColumnComboBox1.AllowFiltering = true;

// Handle text changed for custom filter
multiColumnComboBox1.TextChanged += (sender, e) =>
{
    multiColumnComboBox1.Filter = FilterRecords;
};

// Custom filter predicate
private bool FilterRecords(object o)
{
    var item = o as DataRowView;
    if (item != null)
    {
        string searchText = multiColumnComboBox1.TextBox.Text.ToLower();
        
        // Filter by any column
        return item["ProductName"].ToString().ToLower().Contains(searchText) ||
               item["Category"].ToString().ToLower().Contains(searchText);
    }
    return false;
}

Pattern 3: Hide Specific Columns and Get Selected Data

模式3：隐藏指定列并获取选中数据

csharp
// Load data
DataTable products = GetProductData();
multiColumnComboBox1.DataSource = products;
multiColumnComboBox1.DisplayMember = "ProductName";
multiColumnComboBox1.ValueMember = "ProductID";

// Hide internal ID columns
multiColumnComboBox1.ListBox.Grid.Model.Cols.Hidden["ProductID"] = true;
multiColumnComboBox1.ListBox.Grid.Model.Cols.Hidden["SupplierID"] = true;

// Handle selection to get all column data
multiColumnComboBox1.SelectedValueChanged += (sender, e) =>
{
    if (multiColumnComboBox1.SelectedIndex != -1)
    {
        DataRowView row = multiColumnComboBox1.Items[multiColumnComboBox1.SelectedIndex] as DataRowView;
        
        string productName = row["ProductName"].ToString();
        decimal price = Convert.ToDecimal(row["Price"]);
        string category = row["Category"].ToString();
        
        MessageBox.Show($"Selected: {productName}\nPrice: {price:C}\nCategory: {category}");
    }
};
csharp
// Load data
DataTable products = GetProductData();
multiColumnComboBox1.DataSource = products;
multiColumnComboBox1.DisplayMember = "ProductName";
multiColumnComboBox1.ValueMember = "ProductID";

// Hide internal ID columns
multiColumnComboBox1.ListBox.Grid.Model.Cols.Hidden["ProductID"] = true;
multiColumnComboBox1.ListBox.Grid.Model.Cols.Hidden["SupplierID"] = true;

// Handle selection to get all column data
multiColumnComboBox1.SelectedValueChanged += (sender, e) =>
{
    if (multiColumnComboBox1.SelectedIndex != -1)
    {
        DataRowView row = multiColumnComboBox1.Items[multiColumnComboBox1.SelectedIndex] as DataRowView;
        
        string productName = row["ProductName"].ToString();
        decimal price = Convert.ToDecimal(row["Price"]);
        string category = row["Category"].ToString();
        
        MessageBox.Show($"Selected: {productName}\nPrice: {price:C}\nCategory: {category}");
    }
};

Key Properties

核心属性

PropertyTypeDescription
DataSourceobjectData source for the combobox (DataTable, DataView, DataSet, List<T>)
DisplayMemberstringName of the data source property to display in the text area
ValueMemberstringName of the data source property to use as the value
MultiColumnboolEnables/disables multiple columns (true by default)
ShowColumnHeaderboolShows or hides column headers in dropdown
AllowFilteringboolEnables custom filtering support
FilterPredicate<object>Custom filter predicate for filtering items
StyleVisualStyleVisual theme (Office2003, OfficeXP, VS2005, Office2007, Metro, Office2016*)
Office2007ColorThemeOffice2007ThemeOffice 2007 color scheme (Blue, Silver, Black, Managed)
AlphaBlendSelectionColorColorColor for alpha-blended selection highlighting
DropDownWidthintWidth of the dropdown popup in pixels
ListBox.GridGridListControlAccess to the underlying grid for column customization
属性类型描述
DataSourceobject组合框的数据源（支持DataTable、DataView、DataSet、List<T>）
DisplayMemberstring文本区域展示的数据源属性名称
ValueMemberstring作为值使用的数据源属性名称
MultiColumnbool启用/禁用多列（默认开启）
ShowColumnHeaderbool展示或隐藏下拉列表中的列头
AllowFilteringbool启用自定义过滤支持
FilterPredicate<object>用于过滤条目的自定义过滤谓词
StyleVisualStyle视觉主题（Office2003、OfficeXP、VS2005、Office2007、Metro、Office2016*）
Office2007ColorThemeOffice2007ThemeOffice 2007配色方案（蓝色、银色、黑色、托管）
AlphaBlendSelectionColorColor透明度混合的选中高亮颜色
DropDownWidthint下拉弹窗的宽度（单位：像素）
ListBox.GridGridListControl访问底层网格以自定义列

Common Use Cases

常见使用场景

  1. Employee Lookup: Select employees showing ID, Name, Department, Position in dropdown
  2. Customer Selection: Display customer records with multiple fields (Name, Company, Contact, Country)
  3. Product Catalog: Select products showing Code, Name, Category, Price, Stock
  4. Invoice Line Items: Choose items displaying SKU, Description, Unit Price, Available Quantity
  5. Database Record Picker: Any scenario requiring selection from multi-field database records
  6. Master-Detail Forms: Parent record selection with related data visible in dropdown
  7. Data Entry Assistance: Lookup helper showing context from related fields
  8. Filtered Search: Type-ahead search across multiple columns for faster selection
  1. 员工查找：选择员工时在下拉列表展示ID、姓名、部门、职位
  2. 客户选择：展示包含多个字段的客户记录（姓名、公司、联系人、国家）
  3. 产品目录：选择产品时展示编码、名称、分类、价格、库存
  4. 发票行项目：选择条目时展示SKU、描述、单价、可用库存
  5. 数据库记录选择器：所有需要从多字段数据库记录中选择的场景
  6. 主从表单：父记录选择时在下拉列表展示关联数据
  7. 数据录入辅助：查找助手展示关联字段的上下文信息
  8. 过滤搜索：跨多列的输入即时搜索，提升选择效率

Additional Resources

额外资源