简介面向 Windows 桌面应用开发者的自定义控件源码包实现了将复选框与组合框集成一体的 CheckComboBox 控件适用于需要在下拉列表中完成多项选择、直观展示勾选状态的场景例如设置偏好或过滤条件时无需展开完整列表即可勾选目标项。压缩包共 2 个文件cpp 与 h 各一个整体仅 5KB头文件负责定义类结构、公开方法与私有成员源文件承载事件处理、状态维护及可选的数据库连接逻辑便于调试时灵活裁剪数据层。目前已吸引 261 人学习下载代码量小、结构清晰适合希望掌握自定义控件封装与复杂交互处理的中初级桌面开发者。通过阅读该实现可以了解如何管理每个列表项的 Checkbox 状态、获取用户选中结果以及如何将 UI 控件与数据绑定解耦为后续扩展其他自定义控件提供可复用的实现思路。 先想一下标准 ComboBox 下拉框谁都用过——点开、选一项、合上单选逻辑简单干脆。但实际项目里我遇到最多的诉求反而是另一类功能列表里要勾选多个权限项查询条件里要一次筛选多条流水号报表里要挑出好几条产线再导出。这种下拉面板里放一排 checkbox的多选下拉WinForms 原生的 ComboBox 做不了于是就得自己写一个带 checkbox 的 combox 控件类。正好这阵子在做一个工单管理类的桌面项目里面不下七八个窗口都要用这种多选下拉。我索性封装成一个独立的控件类任何窗体拖进去就能用。这篇文章就把这个控件类的设计思路、核心代码、以及我踩过的几个坑全部摊开讲适合正在做 WinForms 桌面应用、又不想为了一个多选下拉引入整套第三方 UI 框架的开发者参考。1. 为什么下拉框要带勾选框场景分析与方案选型1.1 最典型的使用场景多选筛选与批量配置先别急着写代码我建议你花十分钟想清楚一件事你要的到底是带 checkbox 的下拉框还是一个能多选的面板。这两者的区别决定了你写出来的是别人能复用的通用控件还是只给自己用的临时工具。从我的实践看带 checkbox 的多选下拉几乎都出现在两类窗口里。第一类是查询条件面板比如订单查询界面用户希望在下拉框里同时勾选已创建、已审核、已发货三种状态而不是点开一次选一个、再点开再选一个。第二类是批量配置场景比如给用户分配角色、给报表勾选要导出的列这些地方勾选完界面上还得清楚地看到到底选了哪几项。这两类场景对控件有一个共同的核心要求勾选项时不能关闭下拉面板。用户在面板里连续打勾到最后点击面板外部或再次点击下拉按钮时才收起。这个交互习惯和原生 ComboBox选完即关完全不同所以从需求第一步就得盯住这个差异。1.2 三条实现路线对比继承重绘、第三方控件、组合封装明确了需求我对比过三条路线。第一条是继承现有 ComboBox 并通过 OwnerDraw 重绘。听起来很华丽实际上在 WinForms 里重绘下拉列表项、画出 checkbox 图案并不难难的是塌缩状态下怎么显示多个选中值、怎么处理键盘交互和滚动条。条目一旦超过一屏重绘的边界情况会非常折磨人。这条路线更适合看起来像 ComboBox、行为也像 ComboBox的单选控件不适合多选。第二条是引入第三方控件比如 DevExpress 的 CheckedComboBoxEdit、Telerik 的 MultiSelectCombo以及各种开源实现。好处是成熟稳定坏处是如果项目本身没有引入这些框架为了一个下拉框背上整套框架的授权和体积非常不划算。而且这些控件升级频繁某次框架升级后某个小属性和你的现有代码对不上排查成本比你自己改一个类还高。第三条就是我采用的组合封装写一个继承自 Control 的复合控件内部由显示文字的 Label、右侧下拉按钮 Button、承载勾选项的 CheckedListBox、弹出面板 ToolStripDropDown组成。这条路的好处是完全可控、零依赖、好调试缺点是所有细节都要自己处理。对有经验的开发者来说这个工作量完全可接受而且处理完一轮之后这个控件类就变成项目里的固定资产后续所有窗体都能复用。我把三条路线的对比整理成下面这个表方案外部依赖交互可控性开发量适用场景继承 ComboBox OwnerDraw无一般多选显示难做大只是要单选美化第三方控件DevExpress/Telerik重受制于框架小项目已引入该框架组合封装自定义控件无完全可控中通用多选下拉可复用1.3 为什么我选了组合封装的方案选第三条还有一个很现实的原因项目里已有七八个窗口需要这个功能。如果每个窗口各写一套多选下拉后续需求一变——比如分隔符从逗号改成顿号、显示文本里要加个共选 N 项——那就是全局挨个改的噩梦。抽成一个控件类所有改动集中在一个类文件里这正是控件类这三个字的核心价值。组合封装还有个隐藏优势可视化设计器里可以直接把控件拖到窗体上在属性面板里编辑 Items 集合。这对非核心开发者特别友好调界面的时候不用去翻代码字符串。2. 设计这个控件类前必须想清楚的三件事2.1 界面布局显示框、按钮、弹层怎么摆控件的塌缩状态长得像一个只读的输入框左侧显示已勾选文本右侧有一个向下箭头按钮外部画一圈边框。注意这里我刻意用了 Label 而不是 TextBox 来做文本显示原因后面会讲但核心是 Label 自带 AutoEllipsis文本超宽时能自动省略号TextBox 做不到这一点。弹层打开后是一个比控件本身略宽的面板里面放 CheckedListBox。面板的宽度如果和控件一致滚动条出现时会挤压勾选区域视觉上有点局促所以我一般把弹层宽度做成控件宽度的 1.5 倍左右最长不超过一屏。布局上还有个细节下拉按钮要用 Dock 靠右让它在控件宽度变化时始终贴着右侧左侧的 Label 用 Anchor 左右拉伸并在按钮宽度基础上再减几个像素避免文本被按钮盖住。这些尺寸关系在 Resize 事件里统一计算不要在构造器里写死。2.2 弹出层承载方式为什么用 ToolStripDropDown弹层有几种做法自定义无边框 Form、ToolStripDropDown、或者继承 ToolStripDropDown 自己画。我选了 ToolStripDropDown核心原因是它自带点击外部区域自动关闭的机制而且不会抢焦点弹出的层级天然在最上面不用担心被其他窗体盖住。自定义 Form 需要自己处理 Deactivate 事件来判断是否失焦关闭还要设置 FormBorderStyle.None、ShowWithoutActivation 这些属性细节非常多。ToolStripDropDown 把这些封装好了我只需要关心关闭时要取消哪些情况。注意它有个很管用的重载Show(Point)接受屏幕坐标正好可以算控件的左下角作为弹层起点。2.3 对外接口设计属性、事件、传值方式这个控件类和原生控件的最大区别在于数据模型。原生的 ComboBox 是单选 SelectedItem而多选下拉必须暴露一组勾选项。我最终对外暴露的接口是这样设计的Items直接透传 CheckedListBox 的集合设计期可以编辑。DataSource / DisplayMember / ValueMember支持绑定用法和 ListControl 一致。Separator显示文本的分隔符默认中文顿号。SelectedItemsChanged事件任意项勾选状态变化后触发。GetCheckedValuesT()按泛型取出所有勾选项的 Value 列表。SetCheckedValuesT(IEnumerableT)用一组值反推勾选状态用于回显。CheckAll() / UnCheckAll()一键全选/清空。这套接口的取舍原则是怎么顺手怎么来。取值用 Value 而不是整行对象因为大多数业务场景最后要的是 ID 列表回显用SetCheckedValues而不是逐个设SetItemChecked因为回显往往发生在窗体加载时一次方法调用比循环清晰得多。3. 手写 CheckedComboBox核心代码与关键机制3.1 控件骨架与界面初始化下面是我实际在用的核心类代码为了帖子可读性我压缩了注释项目里建议写完整 XML 注释using System; using System.Collections.Generic; using System.ComponentModel; using System.Drawing; using System.Linq; using System.Windows.Forms; namespace JX.Common.Controls { public class CheckedComboBox : Control { private readonly Label _lblDisplay new Label(); private readonly Button _btnToggle new Button(); private readonly CheckedListBox _chkList new CheckedListBox(); private readonly ToolStripDropDown _popup new ToolStripDropDown(); private string _separator 、; public event EventHandler SelectedItemsChanged; public CheckedComboBox() { SetStyle(ControlStyles.OptimizedDoubleBuffer | ControlStyles.AllPaintingInWmPaint | ControlStyles.ResizeRedraw, true); _lblDisplay.Location new Point(3, 2); _lblDisplay.AutoEllipsis true; _lblDisplay.BackColor Color.White; _lblDisplay.TextAlign ContentAlignment.MiddleLeft; _btnToggle.Text ▾; _btnToggle.Width 22; _btnToggle.Dock DockStyle.Right; _btnToggle.Cursor Cursors.Hand; Controls.Add(_lblDisplay); Controls.Add(_btnToggle); _chkList.BorderStyle BorderStyle.None; _chkList.CheckOnClick true; _chkList.IntegralHeight false; _chkList.Height 180; _chkList.Width 200; var host new ToolStripControlHost(_chkList) { AutoSize false, Padding Padding.Empty, Margin Padding.Empty }; _popup.Padding Padding.Empty; _popup.Margin Padding.Empty; _popup.AutoSize false; _popup.Items.Add(host); _popup.Width _chkList.Width 4; _popup.Height _chkList.Height 4; Size new Size(200, 26); MinimumSize new Size(100, 24); _btnToggle.Click (s, e) ToggleDropDown(); _lblDisplay.Click (s, e) ShowDropDown(); _chkList.ItemCheck OnItemCheck; _popup.Closing OnPopupClosing; } protected override void OnResize(EventArgs e) { base.OnResize(e); if (_lblDisplay null) return; _lblDisplay.Width Math.Max(0, ClientSize.Width - _btnToggle.Width - 8); _lblDisplay.Height ClientSize.Height - 4; } protected override void OnPaint(PaintEventArgs e) { base.OnPaint(e); var rect ClientRectangle; rect.Width - 1; rect.Height - 1; ControlPaint.DrawBorder(e.Graphics, rect, SystemColors.ControlDark, ButtonBorderStyle.Solid); } } }初始化代码里我做了三件关键事一是用SetStyle开了双缓冲防止拖动窗体时边框和文本闪烁二是把 CheckedListBox 塞进ToolStripControlHost再放进 ToolStripDropDown这是弹层能正确显示的核心三是把边框绘制放在 OnPaint 里而不是给控件设BorderStyle因为 Control 基类没有 BorderStyle 属性自绘边框最灵活。3.2 下拉面板的开关与自动关闭处理弹层开关是这类控件最容易出 bug 的地方。我最终的处理逻辑是这样private void ToggleDropDown() { if (_popup.Visible) HideDropDown(); else ShowDropDown(); } private void ShowDropDown() { if (_chkList.Items.Count 0) return; var pos PointToScreen(new Point(0, Height)); _popup.Show(pos); } private void HideDropDown() { _popup.Close(); } private void OnPopupClosing(object sender, ToolStripDropDownClosingEventArgs e) { if (e.CloseReason ! ToolStripDropDownCloseReason.AppClicked) return; var mousePos Control.MousePosition; var rect RectangleToScreen(ClientRectangle); if (rect.Contains(mousePos)) { e.Cancel true; } }为什么这样写ToolStripDropDown 默认 AutoClose 为 true用户点击弹层外部时会自动关闭并且 CloseReason 是 AppClicked。此时如果点击的是我们控件本身比如点了一下下拉按钮必须先取消这次关闭让 Click 事件去处理隐藏弹层的逻辑否则会出现弹层闪一下关上又立刻重新弹开的抖动。OnPopupClosing里判断鼠标位置是否落在控件矩形内是为了拦截这一下把开关逻辑收口到ToggleDropDown里统一处理。3.3 勾选事件刷新时机与文本拼接ItemCheck 事件是整个控件最阴险的地方。它在 checkbox 状态还没改变之前触发如果在这里直接刷新文本拿到的还是旧状态。我的处理是用 BeginInvoke 把刷新延后到状态更新完成之后private void OnItemCheck(object sender, ItemCheckEventArgs e) { BeginInvoke((MethodInvoker)(() { RefreshDisplayText(); SelectedItemsChanged?.Invoke(this, EventArgs.Empty); })); } public void RefreshDisplayText() { var selected _chkList.CheckedItems.Castobject().ToList(); if (selected.Count 0) { _lblDisplay.Text ; _lblDisplay.ForeColor Color.Gray; return; } var texts selected.Select(item _chkList.GetItemText(item)).ToList(); _lblDisplay.Text string.Join(_separator, texts); _lblDisplay.ForeColor Color.Black; }这里我用GetItemText而不是直接ToString()是因为绑定数据源时它内部已经处理了 DisplayMember 的反射逻辑比你自己判断省事得多。空选状态下我把文字置灰给用户一个视觉提示这个条件没有被设置过。3.4 对外取值赋值的完整封装取值和回显是最影响开发体验的部分。我最终给出的封装是这样的public ListT GetCheckedValuesT() { var list new ListT(); foreach (var item in _chkList.CheckedItems) { if (string.IsNullOrEmpty(ValueMember)) { list.Add((T)item); } else { var prop item.GetType().GetProperty(ValueMember); if (prop ! null) list.Add((T)prop.GetValue(item, null)); } } return list; } public void SetCheckedValuesT(IEnumerableT values) { var set new HashSetT(values); for (int i 0; i _chkList.Items.Count; i) { var item _chkList.Items[i]; object itemValue item; if (!string.IsNullOrEmpty(ValueMember)) { var prop item.GetType().GetProperty(ValueMember); itemValue prop?.GetValue(item, null); } _chkList.SetItemChecked(i, itemValue ! null set.Contains((T)itemValue)); } RefreshDisplayText(); } public void CheckAll() { for (int i 0; i _chkList.Items.Count; i) _chkList.SetItemChecked(i, true); RefreshDisplayText(); } public void UnCheckAll() { for (int i 0; i _chkList.Items.Count; i) _chkList.SetItemChecked(i, false); RefreshDisplayText(); }SetCheckedValues 用 HashSet 把查找从 O(n) 降到 O(1)列表项几十条时感觉不明显但做个好习惯没坏处。取值时注意必须遍历CheckedItems很多人第一次会写成SelectedItems在 CheckedListBox 里 SelectedItems 表示的是高亮的行跟 checkbox 勾选完全是两回事这个坑我后面专门讲。4. 实际使用中踩过的坑与排查实录4.1 ItemCheck 事件读取旧状态为什么必须 BeginInvoke这个坑折磨了我一个下午。最初我在 ItemCheck 里直接调 RefreshDisplayText结果文本永远慢一拍勾了第二项界面上只有第一项。原因就是前面说的ItemCheck 在状态变更前触发。排查的方法很简单在事件里加了一行输出 e.CurrentValue 和调用后的 CheckedItems.Count对比之后就明白了。用 BeginInvoke 把刷新放到消息队列尾部等 CheckedListBox 内部状态更新完成后再执行问题就解决了。注意这不是万金油如果你在弹层关闭时也要刷新文本要单独在Closing事件里同步执行一次因为弹层关闭时消息循环的顺序不可控。4.2 点击控件本身导致下拉面板闪一下关闭弹层打开状态下用户想点下拉按钮收起面板。按直觉应该直接收起来但实际会先出现关闭 → 重开的闪烁。原因是 ToolStripDropDown 的 AutoClose 机制先捕获了这次点击把 CloseReason 置为 AppClicked触发了 Closing如果我们在 Closing 里不拦截默认就关了但紧接着按钮的 Click 事件又执行了 ToggleDropDown看到 Visible 已经 true又把它打开了。解决思路就是 3.2 节里的代码在 Closing 里判断鼠标位置如果落在控件矩形内就e.Cancel true让这次关闭作废交给 Click 事件统一处理。这个位置判断 拦截关闭的组合是在 WinForms 里做自绘下拉弹层最常用的套路。4.3 显示文本过多时被截断与弹层宽度不匹配塌缩状态下选中项过多文本会超长。用 Label 的 AutoEllipsis 可以显示省略号但有个视觉问题文本是从左往右截断的设备A、设备B、设备C、……用户看不到最后到底选了什么。更友好的方案是反过来保留尾部或者中间省略。我最终的做法是在 RefreshDisplayText 里做了字符裁剪当文本超过 Label 宽度时保留前几个字符和最后几个字符中间用省略号替代。具体字符数可以用 TextRenderer.MeasureText 挨个试虽然有点笨但效果很直观。另外弹层宽度如果设定得比控件窄出现滚动条时勾选区域会被压缩建议弹层宽度设置为控件宽度的 1.2 到 1.5 倍。4.4 绑定 DataTable 后取值取到 DisplayMember 还是 ValueMember使用DataSource绑定 DataTable 时CheckedItems 里装的是 DataRowView不是原始值。如果 ValueMember 设置的是Id列DisplayMember 是Name列直接用item.ToString()取出来的会是什么我测试下来的结果是取到 DisplayMember 的文本而不是 Id。所以 GetCheckedValues 里必须要反射 ValueMember 指定的属性否则你拿到的值根本没法用于后续查询。还有一点绑定模式下在设计器里直接编辑 Items 会报错因为 DataSource 优先。我的建议是简单固定选项用 Items动态数据用 DataSource两者不要同时用这是 CheckedListBox 本身的约束封装时绕不开只能在文档里写明。5. 一些使用层面的个人经验最后分享几个我在实际项目里总结的细节。第一这个控件用在查询条件面板时建议把用户上一次勾选的结果持久化下来窗体重新打开时用SetCheckedValues还原。这个体验差异非常明显用户会觉得这个系统记得住我上次的选择虽然实现只是一行方法调用。第二注意下拉箭头字符。代码里用的▾U25BE在不同 Windows 主题下渲染粗细有差异如果你发现按钮上箭头显示不清晰可以换成↓或者干脆用 GraphicsPath 自己画一个箭头图形一劳永逸。第三如果目标窗体上这个控件用得很多每个实例都创建自己的 ToolStripDropDown资源上会有少量浪费。性能要求高的话可以做成弹层复用的模式但大多数业务系统根本感知不到我的建议是先把代码写清楚别过早优化。这套控件类我在多个项目里复用目前没再动过核心结构。你如果在迁移到 WPF 或 Web 端时也遇到同样需求其实设计思路是相通的——显示部分、弹层部分、数据模型三件事拆清楚剩下就是各平台 API 的差异了。本文还有配套的精品资源点击获取