syncfusion-winforms-combodropdown

实现 ComboDropDown

何时使用此技能

当用户需要在 Windows Forms 应用程序中实现 Syncfusion ComboDropDown 控件时，请使用此技能。此技能专为以下场景设计：

1. 灵活承载下拉内容 - 在下拉区域承载任意控件（TreeView、ListView、GridList、DataGrid、自定义控件），不局限于从 ListBox 派生的控件
2. 自定义下拉界面 - 使用比标准组合框提供更丰富数据可视化效果的控件，打造独特的下拉体验
3. 基于树的选择 - 在下拉区域中使用 TreeView 控件实现分层导航
4. 多列选择 - 以网格或多列布局显示数据，便于浏览
5. 复杂的数据交互 - 需要自定义逻辑，在编辑区域和下拉控件之间传递数据的场景
6. 自定义弹出行为 - 完全控制下拉列表的打开、关闭时机及其对用户交互的响应方式
7. 高级控件集成 - 集成具备标准列表选择之外功能的专用控件
8. 由开发者管理同步 - 不适合自动数据绑定、需要手动控制的场景

主要区别： 与 ComboBoxBase（仅承载从 ListBox 派生且内置数据绑定的控件）不同，ComboDropDown 可以承载任意控件，但需要你实现文本框与所承载控件之间的交互逻辑。

不适用场景： 如果你只需要一个搭配 ListBox、CheckedListBox 或 GridListControl 的简单下拉列表，并希望自动处理选择，请改用 ComboBoxBase。

组件概述

ComboDropDown 控件是一种轻量灵活的组合框，提供：

• 通用控件承载 - PopupControl 属性接受任意 Windows Forms 控件
• 分离式架构 - 独立的编辑区域（文本框）和下拉区域（任意控件）
• 由开发者管理交互 - 由你控制选择内容如何传递到文本框，以及反向传递
• 事件驱动的同步 - DropDown 事件（显示前）和 Popup 事件（显示后），用于实现交互逻辑
• 标准组合框外观 - 外观类似常规组合框，但下拉内容不受限制
• 以编程方式控制下拉列表 - 可通过指定关闭类型的方法显示或隐藏弹出窗口
• 全面自定义 - 可配置外观、主题、文本行为和边框样式

架构： ComboDropDown 由两个独立部分组成：

1. 编辑区域 - 用户输入或查看已选值的文本框
2. 下拉区域 - 承载你指定的任意控件的弹出容器

你需要通过事件处理程序连接这两个部分。

文档和导航指南

开始使用

📄 阅读： references/getting-started.md

用户首次设置 ComboDropDown 时使用。内容包括：

• 程序集引用和 NuGet 包安装
• 命名空间导入（Syncfusion.Windows.Forms.Tools）
• 基于设计器的设置（拖放、属性配置）
• 基于代码的设置（以编程方式实例化）
• 设置 PopupControl 属性以关联控件
• 基本的 TreeView 集成示例
• 初始配置和故障排除

事件处理与交互

📄 阅读： references/event-handling.md

当用户需要在组合框文本与承载控件之间实现数据交互时。涵盖：

• DropDown 事件——在下拉列表显示前将文本同步到控件选项
• TreeView/ListView DoubleClick 事件——将选项传回文本
• 以编程方式关闭下拉列表（PopupCloseType.Done）
• Popup 事件——在下拉列表出现后将焦点设置到承载控件
• 用于 TreeView 导航的 FindNode 递归辅助函数
• 完整的 TreeView 交互实现
• GridList 集成模式
• SuppressDropDownEvent 属性
• 事件驱动交互的最佳实践

文本行为与输入控制

📄 阅读： references/text-behavior.md

当用户希望控制编辑区域中的文本输入行为时。涵盖：

• CharacterCasing 属性（Upper、Lower、Normal）
• NumberOnly 属性（限制为数字输入）
• ReadOnly 属性（禁止编辑）
• CaseSensitiveAutocomplete 属性
• MatchFirstCharacterOnly 属性
• 横幅文本支持（BannerTextProvider 集成）
• 每种行为的完整示例

外观自定义

📄 阅读： references/appearance-customization.md

当用户需要自定义控件的视觉外观和边框时。涵盖：

• Border3DStyle 属性（10 种 3D 边框样式）
• BorderSides 属性（指定哪些边显示边框）
• FlatStyle 属性（Flat、System、Standard 模式）
• FlatBorderColor 属性
• 编辑区域外观（Font、ForeColor、BackColor）
• 下拉按钮自定义
• Style 属性依赖关系
• 完整的样式示例

主题与样式

📄 阅读： references/themes-and-styles.md

当用户希望应用视觉主题或 Office 风格外观时。涵盖：

• Style 属性（Office2016 变体、Metro、Office2010/2007/2003、VS2005、Default）
• Office2007ColorTheme 属性（Blue、Silver、Black 配色方案）
• 自定义颜色支持（使用 ApplyManagedColors 的 Managed 主题）
• IgnoreThemeBackground 属性
• 主题与外观属性的交互
• 视觉对比和完整的主题示例

快速入门示例

使用 TreeView 进行设计器设置

// 1. Drag ComboDropDown and TreeView onto form
// 2. Add nodes to TreeView (in designer or code)
// 3. Set TreeView.HideSelection = false
// 4. Set ComboDropDown.PopupControl = treeView1

// Event handlers for interaction
private void comboDropDown1_DropDown(object sender, EventArgs e)
{
    // Before dropdown shown: select TreeNode matching combo text
    if (!string.IsNullOrEmpty(this.comboDropDown1.Text))
    {
        TreeNode matchedNode = FindNode(this.treeView1.Nodes, this.comboDropDown1.Text);
        this.treeView1.SelectedNode = matchedNode;
    }
}

private void treeView1_DoubleClick(object sender, EventArgs e)
{
    // Transfer selected node text to combo
    if (this.treeView1.SelectedNode != null)
    {
        this.comboDropDown1.Text = this.treeView1.SelectedNode.Text;
    }
    
    // Close the dropdown
    this.comboDropDown1.PopupContainer.HidePopup(PopupCloseType.Done);
}

private TreeNode FindNode(TreeNodeCollection nodes, string text)
{
    // Recursively find matching node
    foreach (TreeNode child in nodes)
    {
        if (child.Text == text) return child;
    }
    foreach (TreeNode child in nodes)
    {
        TreeNode matched = FindNode(child.Nodes, text);
        if (matched != null) return matched;
    }
    return null;
}

基于代码的设置

using Syncfusion.Windows.Forms.Tools;

// Create ComboDropDown
ComboDropDown comboDropDown1 = new ComboDropDown();
comboDropDown1.Location = new Point(20, 20);
comboDropDown1.Size = new Size(200, 25);

// Create and configure TreeView
TreeView treeView1 = new TreeView();
treeView1.HideSelection = false;
treeView1.Nodes.Add("Root");
treeView1.Nodes[0].Nodes.Add("Child 1");
treeView1.Nodes[0].Nodes.Add("Child 2");

// Associate TreeView with ComboDropDown
comboDropDown1.PopupControl = treeView1;

// Wire up events
comboDropDown1.DropDown += comboDropDown1_DropDown;
treeView1.DoubleClick += treeView1_DoubleClick;

// Add to form
this.Controls.Add(comboDropDown1);

常见模式

模式 1：TreeView 层次选择

// Setup
comboDropDown1.PopupControl = treeView1;
treeView1.HideSelection = false;

// Sync text → TreeView selection (before dropdown)
comboDropDown1.DropDown += (s, e) => {
    var node = FindNode(treeView1.Nodes, comboDropDown1.Text);
    treeView1.SelectedNode = node;
};

// Sync TreeView selection → text (on double-click)
treeView1.DoubleClick += (s, e) => {
    if (treeView1.SelectedNode != null)
    {
        comboDropDown1.Text = treeView1.SelectedNode.Text;
        comboDropDown1.PopupContainer.HidePopup(PopupCloseType.Done);
    }
};

模式 2：多列网格选择

// Host a GridList control for multi-column data
GridListControl gridList = new GridListControl();
// Configure grid columns and data...

comboDropDown1.PopupControl = gridList;

// Sync selection to combo text using the grid's current cell/model
gridList.DoubleClick += (s, e) => {
    var cell = gridList.CurrentCell;
    if (cell != null)
    {
        int row = cell.RowIndex;
        // Read display text from the model (adjust column index as needed)
        comboDropDown1.Text = gridList.Model[row, 1].Text;
        comboDropDown1.PopupContainer.HidePopup(PopupCloseType.Done);
    }
};

模式 3：鼠标交互的焦点管理

// Make dropdown control respond to mouse immediately
comboDropDown1.PopupContainer.Popup += (s, e) => {
    // Give focus to hosted control after dropdown shown
    treeView1.Focus();
};

关键属性

PopupControl 设置

属性	类型	描述	使用时机
PopupControl	Control	下拉列表中显示的控件	设置为要承载的任意 Windows Forms 控件

文本行为

属性	类型	描述	使用时机
Text	string	编辑区域中显示的文本	获取/设置组合框的当前文本值
CharacterCasing	CharacterCasing	Upper、Lower 或 Normal	强制输入大写或小写字符
NumberOnly	bool	将输入限制为数字	仅限数字的场景
ReadOnly	bool	禁止编辑	仅供显示，选项从下拉列表中选择

下拉控件

属性	类型	描述	使用时机
PopupContainer	PopupControlContainer	管理弹出行为的容器	访问 HidePopup() 或 Popup 事件
SuppressDropDownEvent	bool	禁止触发 DropDown 事件	在特定场景中跳过同步逻辑

外观

属性	类型	描述	使用时机
Border3DStyle	Border3DStyle	3D 边框外观（10 种样式）	FlatStyle 为 Standard 时自定义边框外观
BorderSides	Border3DSide	哪些边带有边框	自定义边框配置
FlatStyle	FlatStyle	Flat、System 或 Standard	控制整体外观模式
FlatBorderColor	Color	Flat 模式下的边框颜色	自定义边框颜色

主题

属性	类型	描述	使用时机
Style	VisualStyle	Office2016Colorful、Metro、Office2010 等	应用现代视觉主题
Office2007ColorTheme	Office2007Theme	Blue、Silver、Black 配色方案	使用 Office 2007 风格外观
IgnoreThemeBackground	bool	使用 BackColor 而非主题背景	覆盖主题背景

常见用例

1. 使用 TreeView 的文件系统导航器

场景： 用户需要浏览分层的文件／文件夹结构
解决方案： 承载显示目录树的 TreeView，并将所选路径同步到组合框文本

2. 使用多列网格的类别选择

场景： 用户需要从包含多个显示列的分类数据中进行选择
解决方案： 承载带有类别、名称和描述列的 GridListControl

3. 使用日历控件的日期选择器

场景： 用户需要带可视日历的自定义日期选择器
解决方案： 承载 MonthCalendar 或自定义日历控件，并将所选日期传递到文本

4. 使用自定义面板的颜色选择器

场景： 用户需要从可视调色板中选择颜色
解决方案： 承载带有颜色样本的自定义面板，并将颜色名称／十六进制值传递到文本

ComboDropDown 与 ComboBoxBase 选择指南

在以下情况选择 ComboDropDown：

• ✅ 需要承载 TreeView、ListView、DataGrid 或任何自定义控件
• ✅ 希望完全控制文本 ↔ 控件同步逻辑
• ✅ 需要超出标准选择功能的自定义弹出行为
• ✅ 构建分层导航或复杂数据可视化
• ✅ 标准 ListBox 功能无法满足需求

在以下情况选择 ComboBoxBase：

• ❌ 只需要 ListBox、CheckedListBox 或 GridListControl（简单列表）
• ❌ 希望自动进行数据绑定和选择处理
• ❌ 倾向于使用内置的 SelectionChangedCommitted 事件
• ❌ 不需要自行管理交互逻辑
• ❌ 标准下拉列表功能已能满足需求

主要区别： ComboDropDown = 最大灵活性 + 手动实现；ComboBoxBase = 仅支持 ListBox + 自动处理