syncfusion-winforms-comboboxbase

实现 ComboBoxBase

介绍如何为 Windows Forms 应用程序实现 Syncfusion ComboBoxBase 控件。ComboBoxBase 将编辑部分与下拉列表分离，提供了标准组合框的灵活替代方案，并支持可插拔的 ListControl 架构。

何时使用此技能

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

• 实现具有分离式编辑区和下拉列表架构的灵活组合框
• 在下拉区域使用自定义的 ListControl 派生控件
• 集成 CheckedListBox 以创建多选组合框
• 使用 GridListControl 创建多列下拉列表
• 处理复杂的选择事件和下拉行为
• 需要比标准 Framework 组合框更精细的控制
• 构建具有自定义弹出容器的组合框
• 使用鼠标交互实现快速选择功能

**注意：**如果需要类似 Framework 组合框的对象模型，可以考虑使用 ComboBoxAdv（基于 ComboBoxBase，但对象模型相同）。

组件概述

ComboBoxBase 控件将编辑部分（TextBox）与下拉列表部分分离，使其架构更加强大灵活。你可以通过 ListControl 属性插入任意 ListControl 派生类（ListBox、CheckedListBox、GridListControl）。

主要功能：

• 可插拔的 ListControl 架构
• 支持 ListBox、CheckedListBox 和自定义 ListControl
• 使用 GridListControl 创建多列下拉列表
• 为各种选择场景提供全面的事件处理
• 样式和外观自定义
• 与 PopupControlContainer 集成
• 使用鼠标交互实现 QuickSelection

架构差异：

• 与标准组合框不同，编辑部分和列表部分彼此独立
• 对象模型不同于 Framework 组合框
• DataSource、ItemHeight 等属性设置在 ListControl 上，而非 ComboBoxBase 上
• SelectedIndexChanged 等事件由 ListControl 处理

文档与导航指南

入门

📄 阅读： references/getting-started.md

• 安装和程序集引用
• 基于设计器的设置（拖放）
• 基于代码的实例化
• 将 ListBox 连接到 ComboBoxBase
• 配置 DataSource
• 完整的设置示例

ListControl 架构

📄 阅读： references/listcontrol-architecture.md

• ListControl 属性说明
• 创建自定义 ListControl 派生控件
• 必需的属性和方法（Items、IndexFromPoint、TopIndex）
• 集合类（ObjectCollection、SelectedObjectCollection、SelectedIndexCollection）
• 实现 QuickSelection 功能
• 使用 GridListControl 创建多列下拉列表
• 与各种列表控件集成

事件处理

📄 阅读： references/event-handling.md

• 选择事件（SelectionChangedCommitted、SelectedValueChanged、SelectedIndexChanged）
• 事件顺序和场景
• CheckedListBox 的 DropDownCloseOnClick 事件
• PopupControlContainer 的 DropDown 事件
• Validating/Validated 事件
• 完整的 CheckedListBox 集成示例

外观与行为

📄 阅读： references/appearance-behavior.md

• Style 和 FlatStyle 属性
• 边框绘制自定义
• TextBox 和下拉窗口样式
• 与 Framework 组合框的属性对比
• ComboBoxAdv 对比
• 视觉样式示例

高级场景

📄 阅读： references/advanced-scenarios.md

• CheckedListBox 多选模式
• 自定义 PopupControlContainer 派生类
• 使用 OnPopup 重写来管理焦点
• 在 PopupControlContainer 中嵌套 ComboBoxBase
• PopupParent 和 CurrentPopupChild 关系
• 复杂的下拉场景

快速入门

设计器设置

步骤 1：将 ComboBoxBase 添加到 Form

1. Open your WinForms project in Visual Studio
2. Drag ComboBoxBase from Toolbox to Form
3. Drag ListBox from Toolbox to Form
4. In ComboBoxBase Properties, set ListControl = listBox1

代码设置

基本实现：

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

public partial class Form1 : Form
{
    private ComboBoxBase comboBoxBase1;
    private ListBox listBox1;
    
    public Form1()
    {
        InitializeComponent();
        SetupComboBoxBase();
    }
    
    private void SetupComboBoxBase()
    {
        // Create ComboBoxBase and ListBox
        comboBoxBase1 = new ComboBoxBase();
        listBox1 = new ListBox();
        
        // Configure ComboBoxBase
        comboBoxBase1.Size = new Size(200, 25);
        comboBoxBase1.Location = new Point(20, 20);
        comboBoxBase1.ListControl = listBox1; // Connect ListBox
        
        // Add items to ListBox
        listBox1.Items.AddRange(new object[] {
            "Option 1",
            "Option 2",
            "Option 3",
            "Option 4"
        });
        
        // Add to form
        this.Controls.Add(listBox1);
        this.Controls.Add(comboBoxBase1);
    }
}

VB.NET：

Imports Syncfusion.Windows.Forms.Tools
Imports System.Windows.Forms

Public Class Form1
    Private comboBoxBase1 As ComboBoxBase
    Private listBox1 As ListBox
    
    Public Sub New()
        InitializeComponent()
        SetupComboBoxBase()
    End Sub
    
    Private Sub SetupComboBoxBase()
        ' Create ComboBoxBase and ListBox
        comboBoxBase1 = New ComboBoxBase()
        listBox1 = New ListBox()
        
        ' Configure ComboBoxBase
        comboBoxBase1.Size = New Size(200, 25)
        comboBoxBase1.Location = New Point(20, 20)
        comboBoxBase1.ListControl = listBox1 ' Connect ListBox
        
        ' Add items to ListBox
        listBox1.Items.AddRange(New Object() {
            "Option 1",
            "Option 2",
            "Option 3",
            "Option 4"
        })
        
        ' Add to form
        Me.Controls.Add(listBox1)
        Me.Controls.Add(comboBoxBase1)
    End Sub
End Class

常见模式

模式 1：使用 DataSource 的 ComboBoxBase

// Create data source
List<string> states = new List<string> 
{ 
    "California", "Texas", "Florida", "New York" 
};

// Set DataSource on ListBox (not ComboBoxBase)
listBox1.DataSource = states;
comboBoxBase1.ListControl = listBox1;

模式 2：CheckedListBox 集成

// Use CheckedListBox for multi-select
CheckedListBox checkedListBox1 = new CheckedListBox();
checkedListBox1.Items.AddRange(new object[] {
    "Item 1", "Item 2", "Item 3", "Item 4"
});

comboBoxBase1.ListControl = checkedListBox1;

// Handle DropDownCloseOnClick to prevent premature closing
comboBoxBase1.DropDownCloseOnClick += (sender, e) => {
    e.Cancel = true; // Keep dropdown open while selecting
};

// Update text with checked items
checkedListBox1.ItemCheck += (sender, e) => {
    // Build text from checked items
    var checkedItems = checkedListBox1.CheckedItems.Cast<object>();
    comboBoxBase1.TextBox.Text = string.Join(", ", checkedItems);
};

模式 3：自定义对象数据源

public class Employee
{
    public int Id { get; set; }
    public string Name { get; set; }
    public override string ToString() => Name;
}

// Create employee list
List<Employee> employees = new List<Employee>
{
    new Employee { Id = 1, Name = "John Doe" },
    new Employee { Id = 2, Name = "Jane Smith" },
    new Employee { Id = 3, Name = "Bob Johnson" }
};

listBox1.DataSource = employees;
listBox1.DisplayMember = "Name"; // Display property
listBox1.ValueMember = "Id";     // Value property

comboBoxBase1.ListControl = listBox1;

关键属性

ComboBoxBase 属性

属性	类型	描述
ListControl	IListControl	获取或设置用于下拉列表的 ListControl 派生控件
TextBox	TextBox	获取控件的 TextBox 部分
PopupContainer	PopupControlContainer	获取下拉列表的弹出容器
Style	ComboBoxStyle	获取或设置视觉样式
FlatStyle	FlatStyle	获取或设置平面样式外观
Size	Size	获取或设置控件大小

ListControl 属性（在 ListBox/CheckedListBox 上设置）

属性	类型	描述
Items	ObjectCollection	列表中的项目集合
DataSource	object	列表的数据源
DisplayMember	string	对象中用于显示的属性
ValueMember	string	用作值的属性
SelectedItem	object	当前选中的项目
SelectedIndex	int	当前选中的索引
SelectionMode	SelectionMode	单选或多选

重要事件

事件	描述
SelectionChangedCommitted	用户操作提交选择时触发
DropDownCloseOnClick	单击时下拉列表即将关闭时触发（可取消）
DropDown	下拉列表即将打开时触发

注意： SelectedIndexChanged 等事件由 ListControl（ListBox）处理，而非 ComboBoxBase。

使用场景

使用场景 1：简单下拉列表

需要基本的项目下拉列表时，请使用标准 ListBox：

• 显示选项列表
• 单选
• 简单文本项目或对象绑定

使用场景 2：多选下拉列表

用户需要选择多个项目时，请使用 CheckedListBox：

• 筛选选择（多个类别）
• 标签选择
• 权限复选框
• 多值输入

使用场景 3：多列下拉列表

需要在下拉列表中显示表格数据时，请使用 GridListControl：

• 按 ID、姓名、部门选择员工
• 按代码、名称、价格选择产品
• 通过多个字段选择数据库记录

使用场景 4：自定义列表控件

内置控件无法满足需求时，请创建自定义 ListControl：

• 使用图像/图标进行自定义渲染
• 复杂布局
• 专用交互模式

选择指南

以下情况请选择 ComboBoxBase，而非标准组合框：

• 需要可插拔的 ListControl 架构
• 希望使用 CheckedListBox 或自定义控件
• 需要使用 GridListControl 的多列下拉列表
• 需要精细控制编辑部分和列表部分
• 构建复杂的下拉场景

以下情况请选择标准组合框：

• 简单下拉列表即可满足需求
• 更偏好使用框架对象模型
• 不需要自定义 ListControl
• 仅涉及基本选择场景

以下情况请选择 ComboBoxAdv：

• 需要 ComboBoxBase 的灵活性
• 更偏好使用框架组合框对象模型
• 希望兼具强大功能和熟悉的 API

后续步骤

1. 从 getting-started.md 开始，了解基本设置
2. 阅读 listcontrol-architecture.md，了解 ListControl 概念
3. 查看 event-handling.md，了解选择事件
4. 浏览 advanced-scenarios.md，探索复杂使用场景