syncfusion-winforms-multicolumn-combobox

实现多列组合框（MultiColumnComboBox）

一种适用于 Windows Forms 的高级组合框控件，可在下拉列表中显示多列，并支持虚拟数据绑定，以便即时加载大型数据集。

何时使用此技能

在需要以下功能时使用此技能：

• 多列下拉列表：在下拉列表中显示多个数据字段（类似下拉列表中的 DataGridView）
• 大型数据集绑定：绑定大型数据源，并通过虚拟渲染提升性能
• 数据查找：在下拉列表中显示相关字段（ID、名称、描述、类别）
• 实体选择：选择具有多个可见属性的记录
• 筛选下拉列表：对所有列应用自定义筛选
• 设置组合框样式：为下拉控件应用 Office 主题（2003-2019）
• DataSource 绑定：使用 DataSource、DisplayMember 和 ValueMember 属性
• 替换 ComboBox：用功能更丰富的多列显示替换标准 ComboBox

组件概述

MultiColumnComboBox 基于 ComboBoxBase，提供以下功能：

• 在下拉列表中显示多列
• 大型数据集的虚拟数据绑定（即时加载）
• 自动显示数据源中的所有字段
• DataSource、DisplayMember 和 ValueMember 属性
• 通过 ShowColumnHeader 属性显示列标题
• 对所有列进行自定义筛选
• 基于网格的下拉列表（GridListControl）
• 不支持手动添加项（仅支持数据绑定）

主要功能：

• 使用 DataSource 属性绑定数据（DataTable、DataView、DataSet、List）
• 使用 DisplayMember 和 ValueMember 选择列
• 使用 ShowColumnHeader 属性显示列标题
• 使用 AllowFiltering 属性启用自定义筛选
• 使用 Style 属性应用 Office 视觉主题
• 使用 AlphaBlendSelectionColor 自定义选中项的外观
• 使用 DropDownWidth 控制下拉列表宽度

文档和导航指南

入门

📄 阅读： references/getting-started.md

阅读时机： 开始新的实现、首次设置、创建基本控件时

涵盖主题：

• 程序集和命名空间要求（Syncfusion.Windows.Forms.Tools）
• 通过设计器添加（从工具箱拖放）
• 通过代码添加（编程方式创建）
• MultiColumnComboBox 基本实例化
• 集成到窗体中
• 初始设置步骤

---

数据绑定

📄 阅读： references/data-binding.md

阅读时机： 绑定数据源、配置 DataSource/DisplayMember/ValueMember、从数据库或 XML 加载数据时

涵盖主题：

• DataSource、DisplayMember、ValueMember 属性
• 将 DataView 用作数据源
• 在数据库中使用 OleDBDataAdapter
• 填充强类型 DataSet
• 加载 XML 数据（ReadXml）
• 隐藏特定列（Grid.Model.Cols.Hidden）
• 访问所选项的 DataRowView
• 完整的数据绑定示例

---

多列配置

📄 阅读： references/multiple-columns.md

阅读时机： 配置列、启用或禁用多列模式、筛选、设置下拉列表宽度时

涵盖主题：

• MultiColumn 属性（启用/禁用列）
• ShowColumnHeader 属性（显示列标题）
• AlphaBlendSelectionColor（选中高亮颜色）
• DropDownWidth 属性（下拉列表宽度配置）
• AllowFiltering 属性（启用自定义筛选）
• Filter 属性（基于谓词进行筛选）
• 自定义筛选实现
• 默认筛选行为（对 DisplayMember 使用 StartsWith）

外观和样式

📄 阅读： references/appearance-styling.md

适用场景： 应用视觉主题、自定义外观、配置 Office 主题

涵盖主题：

• Style 属性（9 种视觉样式）
• Office2003、OfficeXP、VS2005 样式
• 带配色方案（Blue、Silver、Black）的 Office2007
• Metro、Office2016 变体（Colorful、White、Black、DarkGray）
• Office2007ColorTheme 属性
• 使用 ApplyManagedColors 方法自定义颜色
• 托管主题配置
• 完整的样式示例

---

事件处理

📄 阅读： references/event-handling.md

适用场景： 处理选择变更、响应用户交互、访问所选数据

涵盖主题：

• SelectionChangedCommitted 事件
• SelectedValueChanged 事件
• SelectedIndexChanged 事件
• 事件触发情形和顺序
• 访问所选项数据（DataRowView）
• 根据所选项设置文本
• 完整的事件处理程序示例

---

快速入门示例

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

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

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)

---

常见模式

模式 1：使用 OleDbDataAdapter 查询数据库

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;

模式 2：按任意列自定义筛选

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

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

// 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}");
    }
};

---

主要属性

属性	类型	说明
DataSource	object	组合框的数据源（DataTable、DataView、DataSet、List）
DisplayMember	string	要在文本区域中显示的数据源属性名称
ValueMember	string	用作值的数据源属性名称
MultiColumn	bool	启用/禁用多列（默认启用）
ShowColumnHeader	bool	显示或隐藏下拉列表中的列标题
AllowFiltering	bool	启用自定义筛选支持
Filter	Predicate	用于筛选项的自定义谓词
Style	VisualStyle	视觉主题（Office2003、OfficeXP、VS2005、Office2007、Metro、Office2016*）
Office2007ColorTheme	Office2007Theme	Office 2007 配色方案（Blue、Silver、Black、Managed）
AlphaBlendSelectionColor	Color	Alpha 混合选中高亮的颜色
DropDownWidth	int	下拉弹出窗口的宽度，单位为像素
ListBox.Grid	GridListControl	访问底层网格以自定义列

---

常见用例

1. 员工查询：在下拉列表中显示 ID、姓名、部门和职位，以便选择员工
2. 客户选择：显示包含多个字段的客户记录（姓名、公司、联系方式、国家/地区）
3. 产品目录：显示代码、名称、类别、价格和库存，以便选择产品
4. 发票明细项：显示 SKU、说明、单价和可用数量，以便选择项目
5. 数据库记录选择器：任何需要从多字段数据库记录中进行选择的场景
6. 主从表单：选择父记录，并在下拉列表中查看相关数据
7. 数据录入辅助：通过查询相关字段提供上下文信息
8. 筛选搜索：跨多个列进行输入即搜索，以便更快地选择

---

更多资源

• Syncfusion 帮助中心中的 MultiColumnComboBox 控件
• Syncfusion.Windows.Forms.Tools 命名空间
• MultiColumnComboBox API 参考
• ComboBoxBase API 参考