简介：MFC开发中，工具栏是常用的界面元素，但这套示例工程专注于CToolBar的深度自定义，解决按钮图片与文字同时显示、工具栏停靠与浮动切换等实际开发中的常见问题，适合具有C++基础、正在学习MFC界面编程或希望快速复用工具栏方案的开发者。压缩包总共包含24个文件，压缩后体积仅为324KB，以7个头文件和5个源文件为主体，配套资源脚本、图标、工程配置与可执行程序，同时包含工具栏图片素材和代码说明文档，目录按类型区分清晰，打开解决方案即可对照阅读。目前已有1682人学习下载，代码量适中、注释清晰、逻辑易读，是轻量而完整的MFC工具栏参考示例。通过该示例能够掌握CToolBar的创建与初始化、加载位图资源、添加按钮并设置按钮文字与图像索引的方法，还可以学习停靠与浮动功能的控制方式，以及位图透明区域与按钮样式等细节处理，最终将示例素材和代码直接迁移到实际项目中，无论用于入门学习还是项目改造，都有直接的参考价值。 MFC的CToolBar，说简单也简单，拖一个TOOLBAR资源进来LoadToolBar就出来了；但要是想把按钮做成“图片+文字”的模式，很多人会卡在同一个地方：SetButtonText明明调了，界面上就是不出字；或者字出来了，按钮又窄得没法看。这篇文章就是我从实际改工具栏的经历中整理出来的，把CToolBar工具栏自定义图片及文字这件事，从原理讲到落地，每一步都会说明为什么这么写，以及哪些地方最容易踩坑。
适用人群，说实话，MFC新手和老手都能看。新手可以直接抄代码解决眼前的问题，老手可以重点看后半部分的排查思路和自绘方案取舍，这里面有不少是文档里不会写的细节。
1. 先搞懂CToolBar的默认行为，再动手改
1.1 最常见的“图片不显示”现象背后
很多第一次接触工具栏定制的朋友都会有这个疑惑：我在资源编辑器里放了位图，也写了BUTTON，LoadToolBar也返回成功了，为什么运行起来按钮上什么都没有？
要解释这个，得先搞清楚MFC加载工具栏的完整链路。LoadToolBar内部做了两件事：一是调用LoadBitmap把工具栏位图加载进来，二是通过SetButtons把TOOLBAR资源里定义的按钮一个个创建出来。但这里有一个容易忽略的点：工具栏位图并不是按“文件名”映射到按钮上的，而是按照切图规则逐格分配的。
什么叫切图规则？MFC认为工具栏位图是一张“胶片”，系统会把这张胶片按高度切成若干等宽的小格，每一格对应一个按钮。比如位图高度是32像素，那么系统就从左往右每32像素切一格，第一格给第一个按钮，第二格给第二个按钮，以此类推。按钮的图片索引，本质上是“第几格”的顺序号，而不是命令ID。
所以当你看到“图片不显示”或者“所有按钮显示同一个图标”时，第一反应应该去排查索引对应关系，而不是怀疑位图本身损坏。
1.2 图片+文字的三种主流方案对比
既然默认工具栏只显示图片（甚至图片还经常因为切图问题显示错乱），那要把图片和文字同时展示出来，通常有三条路可走：
| 方案 | 实现方式 | 灵活度 | 复杂度 | 适用场景 |
|---|---|---|---|---|
| 方案一 | SetButtonText + TBSTYLE_LIST 样式 | 中 | 低 | 绝大多数常规场景，改动最小 |
| 方案二 | 底层TBBUTTON结构 + AddButtons | 高 | 中 | 完全代码创建工具栏，不依赖资源编辑器 |
| 方案三 | 继承CToolBar，重绘按钮 | 最高 | 高 | 需要自定义配色、圆角、复杂布局时 |
方案一是这篇文章的主推方案，不仅代码量少，而且和资源编辑器组合使用最顺畅。方案二适合那种“工具栏完全由配置文件驱动”的项目，可以绕过资源编辑器动态生成按钮。方案三则是终极手段，说实话原生MFC在自绘这块支持比较弱，大部分项目要么引入界面库，要么就在DrawItem这条路上深挖，成本不低。
从实际项目经验来看，能选方案一就不要去折腾方案三——除非你的UI设计稿确实提出了“图标在上、文字在下”“不同按钮不同颜色”这类硬性要求，否则在工具栏自绘上投入大量时间，ROI并不高。
2. 标准姿势：SetButtonText实现图片+文字
2.1 创建工具栏并加载图标
先看最基础的创建过程，这段代码通常放在CMainFrame::OnCreate里面：
if (!m_wndToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE | CBRS_TOP | CBRS_GRIPPER | CBRS_TOOLTIPS | CBRS_FLYBY | CBRS_SIZE_DYNAMIC) || !m_wndToolBar.LoadToolBar(IDR_MAINFRAME)) { TRACE0("未能创建工具栏\n"); return -1; // 创建失败时及时返回，避免界面异常 }这里几个样式参数我简单解释一下。TBSTYLE_FLAT是扁平风格的工具栏，现代程序基本都会加。CBRS_TOP控制工具栏停靠在窗口顶部，CBRS_GRIPPER显示左侧的拖动手柄，CBRS_TOOLTIPS启用气泡提示，CBRS_FLYBY允许鼠标悬停在按钮上时显示文字提示，CBRS_SIZE_DYNAMIC让工具栏可以动态改变大小，在浮动状态下尤其好用。
LoadToolBar(IDR_MAINFRAME)加载的是资源编辑器里设计的TOOLBAR资源。如果你想加载自己准备的位图，而不希望用资源编辑器的TOOLBAR，也可以改成：
m_wndToolBar.CreateEx(this); m_wndToolBar.LoadBitmap(IDB_TOOLBAR_ICONS); m_wndToolBar.SetButtons(buttons, nCount);但这种方式需要自己定义TBBUTTON数组，工作量会大一些。
2.2 关键一步：设置文字并显示出来
工具栏创建成功之后，紧接着就可以给按钮加上文字了。很多人在这一步就踩了坑，直接写出这样的代码：
m_wndToolBar.SetButtonText(ID_FILE_NEW, _T("新建"));表面上看起来没问题，但运行起来文字死活不显示。原因有两个：第一，SetButtonText的第一个参数是按钮索引，不是命令ID；第二，没有给工具栏加上TBSTYLE_LIST样式，文字即使设置成功也不会绘制出来。
正确的做法是：
// 先根据命令ID找到按钮在工具栏中的索引 int nIndex = m_wndToolBar.CommandToIndex(ID_FILE_NEW); m_wndToolBar.SetButtonText(nIndex, _T("新建"));CommandToIndex这个函数会把命令ID转换成按钮索引，这是最稳妥的写法，不建议自己手工数索引，因为在有分隔条（Separator）的工具栏里，索引和按钮顺序并不是完全直观对应的。
然后加上最关键的一行：
// 让文字显示在图标右侧 m_wndToolBar.GetToolBarCtrl().ModifyStyle(0, TBSTYLE_LIST);TBSTYLE_LIST的作用是让工具栏按钮把文字标签显示出来，默认情况下工具栏按钮是没有文字区域的，即使SetButtonText赋值了，文字只存在于工具栏内部的字符串链表中，不会绘制到界面上。这个样式一加，文字就会出现在图标的右侧。
最后别忘了这两步：
m_wndToolBar.GetToolBarCtrl().AutoSize(); m_wndToolBar.UpdateWindow();AutoSize会重新计算每个按钮的宽度，把文字和图标完整容纳进去。我在第一次做的时候，就是没写这一步，结果文字出现了但被截掉一半，整个工具栏看起来像残废了一样。UpdateWindow则是强制重绘，确保新样式和文字立即生效。
把完整的代码串起来就是这样：
// 工具栏创建完成后，逐按钮设置文字 int nIdxNew = m_wndToolBar.CommandToIndex(ID_FILE_NEW); int nIdxOpen = m_wndToolBar.CommandToIndex(ID_FILE_OPEN); int nIdxSave = m_wndToolBar.CommandToIndex(ID_FILE_SAVE); m_wndToolBar.SetButtonText(nIdxNew, _T("新建")); m_wndToolBar.SetButtonText(nIdxOpen, _T("打开")); m_wndToolBar.SetButtonText(nIdxSave, _T("保存")); // 显示文字并自动调整尺寸 m_wndToolBar.GetToolBarCtrl().ModifyStyle(0, TBSTYLE_LIST); m_wndToolBar.GetToolBarCtrl().AutoSize(); m_wndToolBar.UpdateWindow();如果按钮比较多，建议建一个std::map<UINT, CString>来维护命令ID和文字的对应关系，循环设置，代码会好维护得多。
注意：
SetButtonText的参数是按钮索引，索引从0开始。如果传了命令ID，即使编译不报错，运行时也不会崩溃，但文字会设置到错误的按钮上甚至直接不显示，这是最常见的隐蔽错误之一。
2.3 让按钮宽度、字体更符合预期
加上TBSTYLE_LIST之后，工具栏会按“图标+文字”的宽度来自适应，但有时候自适应出来的效果并不理想，比如文字太长盖住相邻按钮，或者你希望所有按钮等宽。这时可以手动设置按钮尺寸：
m_wndToolBar.GetToolBarCtrl().SetButtonSize(CSize(90, 32)); // 按钮整体宽度、高度 m_wndToolBar.GetToolBarCtrl().SetBitmapSize(CSize(24, 24)); // 图标显示区域这两个API我是强烈推荐搭配使用的。SetButtonSize控制的是整个按钮的矩形大小，SetBitmapSize控制的是图标区域大小。如果只改前者不改后者，图标和文字的位置比例可能失衡；如果只改后者，按钮尺寸可能不够放文字。先想清楚图标放多大、文字需要多少空间，再倒推按钮尺寸，一般比较合理。
字体方面，工具栏文字默认跟随系统字体，如果你想换字体，可以创建好CFont后调用：
CFont font; font.CreateFont(14, 0, 0, 0, FW_BOLD, FALSE, FALSE, FALSE, DEFAULT_CHARSET, OUT_DEFAULT_PRECIS, CLIP_DEFAULT_PRECIS, CLEARTYPE_QUALITY, DEFAULT_PITCH | FF_DONTCARE, _T("微软雅黑")); m_wndToolBar.GetToolBarCtrl().SetFont(&font);注意，CFont变量必须是成员变量或者类成员，不能是局部变量，否则字体对象在函数返回后就被销毁，工具栏文字会变成乱码或者显示异常。这个坑我见过不止一次。
文字颜色这块要说实话，原生CToolBar没有直接设置文字颜色的API，想改颜色就得走自绘路线或者引入界面库。如果确实有需求，建议评估一下工作量，而不是硬靠原生控件强行实现。
3. 进阶细节：图标美化与动态文字
3.1 用PNG透明图标代替传统BMP位图
传统MFC工具栏位图（BMP）最大的问题是不支持透明通道，图标边缘总是带着一块背景色，视觉上很粗糙。现在大家都习惯用PNG来做图标，好在MFC配合CImage可以轻松实现PNG转工具栏图片列表。
CImageList imgList; imgList.Create(32, 32, ILC_COLOR32, 0, 1); CImage image; image.Load(L".\\res\\icon_open.png"); CBitmap bmp; bmp.Attach(image.Detach()); imgList.Add(&bmp, RGB(255, 0, 255)); // 透明色可以随便填，ILC_COLOR32下基本用不到然后把这个图片列表设置给工具栏：
// 注意这里的顺序：先SetImageList，再设置文字和样式 m_wndToolBar.GetToolBarCtrl().SetImageList(&imgList);有几个细节值得提一下。第一，CImageList和CImage的生命周期必须保证在工具栏使用图片期间一直有效，通常做法是把它们声明为CMainFrame的成员变量，不能在OnCreate里定义成局部变量就完事。第二，image.Detach()和bmp.Attach()的搭配是为了把CImage内部的HBITMAP所有权转移给CBitmap，如果直接imgList.Add(&image, ...)，编译会报错或者行为异常。第三，在ILC_COLOR32格式下，每个图标的Alpha通道会被保留，PNG的半透明边缘也能自然融合。
如果你有多张PNG要一次性加入图片列表，可以循环处理：
CString strPathList[] = { L".\\res\\icon_new.png", L".\\res\\icon_open.png" }; for (int i = 0; i < 2; i++) { CImage image; image.Load(strPathList[i]); CBitmap bmp; bmp.Attach(image.Detach()); imgList.Add(&bmp, RGB(255, 255, 255)); }3.2 高DPI下的清晰度问题
现在高分屏已经很普及了，MFC在高DPI下的表现一直被人诟病。工具栏图标如果用固定像素位图，在DPI缩放后经常出现模糊或者边缘发虚的情况。
一个比较务实的做法是准备两套图标，一套是正常的32x32，一套是48x48甚至64x64，在程序启动时根据当前DPI选择：
UINT nDPI = GetDpiForWindow(GetSafeHwnd()); // 需要Windows 10以上 if (nDPI >= 144) // 150%缩放左右 { imgList.Create(48, 48, ILC_COLOR32, 0, 1); picturePath = L".\\res\\icon_large.png"; } else { imgList.Create(32, 32, ILC_COLOR32, 0, 1); picturePath = L".\\res\\icon_normal.png"; }同时也要配合SetButtonSize和SetBitmapSize同步放大，不然图标大了放不下。这类细节放到实际项目里往往比功能开发更费时间，但不处理又会被测试和用户反复提问题。
3.3 运行期动态修改按钮文字
有些工具栏按钮的文字需要随程序状态动态变化，比如“开始/停止”“锁定/解锁”。实现方式也很简单，在状态切换的地方重新设置文字并刷新：
void CMainFrame::OnToggleState() { static BOOL bStarted = FALSE; bStarted = !bStarted; int nIdx = m_wndToolBar.CommandToIndex(ID_APP_TOGGLE); m_wndToolBar.SetButtonText(nIdx, bStarted ? _T("停止") : _T("开始")); m_wndToolBar.GetToolBarCtrl().AutoSize(); // 文字长度变化后必须重新自适应 m_wndToolBar.UpdateWindow(); }这里要特别提醒：文字长度变化后，按钮宽度不会自动更新，所以AutoSize必须再次调用。如果不调用，长文字会被截断，短文字又会留下一大块空白。我在第一次做动态文字的时候就在这里吃了亏，写完代码在对话框里切换状态，文字设置了好几次，界面始终显示第一次的长度，查了半天才发现是AutoSize的问题。
4. 常见问题与排查技巧实录
4.1 文字设置了却不显示
这个问题排名第一，几乎每个做工具栏定制的人都会遇到。排查顺序我建议按以下步骤走：
| 序号 | 排查项 | 原因与处理 |
|---|---|---|
| 1 | 是否加了TBSTYLE_LIST样式 | 没加这个样式，文字不会被绘制，直接ModifyStyle补上 |
| 2 | SetButtonText传的是索引还是ID | 传ID不会报错但文字不会出现在正确位置，用CommandToIndex转换 |
| 3 | 是否调用了AutoSize | 没有重算尺寸时文字可能被挤出可视区域，补调AutoSize |
| 4 | 工具栏创建后是否被SetButtonSize覆盖 | 手动设置了过小的按钮尺寸会截断文字，调整按钮尺寸 |
我个人排查时一般按这个顺序从上到下过一遍，80%的问题都能解决。剩下20%通常和自绘、第三方界面库冲突有关，需要单独看代码。
4.2 图标显示错乱、空白、花屏
图标错乱基本可以锁定为索引问题，可能原因有这么几种。第一，位图切图时，图标格数少于按钮数，多余的按钮会显示空图标。第二，图片列表里第一格是空图标位（很多老资源里第一格故意留空），但你直接用了默认加载方式，导致所有按钮显示错位一个格子。第三，给工具栏分配图片列表的时机不对，覆盖了原有的图标映射。
我的建议是：排查时先把图片列表的数量打印出来，再对照按钮数量看差异：
CString strInfo; strInfo.Format(_T("按钮数量: %d, 图片数量: %d"), m_wndToolBar.GetToolBarCtrl().GetButtonCount(), m_wndToolBar.GetToolBarCtrl().GetImageList()->GetImageCount()); TRACE(strInfo);另外，位图宽度必须能被图标高度整除。比如图标高度32，位图宽度如果是33这种，最后一列会被裁剪出残缺图标。这个是在资源准备阶段就要注意的事，别把图片排得歪七扭八再拽进资源编辑器。
4.3 中文乱码与字符串转换问题
MFC日常开发里，CString和char互相转换是个经典问题。在Unicode工程下，直接把CString强转成const char只能拿到首字符，中文直接乱码。正确做法是用CT2A或者CW2A：
CString strText = _T("你好"); CT2A szText(strText); // CString -> char* const char* pChar = szText.m_psz;反过来，char*转CString用CA2T：
char szBuf[64] = "hello"; CA2T tszText(szBuf); // char* -> CString CString strResult = tszText;这几个宏在atlconv.h里，使用前记得包含头文件。为什么我会在工具栏这篇里提这个？因为做工具栏按钮文字动态更新时，经常会从配置文件或者外部接口读入文本，而这些来源多半是char*，转换不当就会出现中文乱码。在VS2013及以前，字符集设置对编译结果影响非常大，遇到乱码先确认工程字符集是Unicode还是多字节，再决定转换方案。
4.4 功能按钮点击没反应
工具栏按钮点击事件走消息映射，如果添加了按钮但命令ID没有映射处理函数，按钮会显示为灰色不可点击。这是新手常遇到的问题，属于正常表现，不是Bug。
还有一种情况是按钮ID映射了处理函数但工具栏没有触发，多半是ON_UPDATE_COMMAND_UI和ON_COMMAND宏写的位置不对，或者类类型匹配错误。检查一下消息映射宏是否正确写在CMainFrame的消息映射表里：
BEGIN_MESSAGE_MAP(CMainFrame, CFrameWnd) ON_COMMAND(ID_FILE_NEW, &CMainFrame::OnFileNew) ON_UPDATE_COMMAND_UI(ID_FILE_NEW, &CMainFrame::OnUpdateFileNew) END_MESSAGE_MAP()ON_UPDATE_COMMAND_UI用于控制按钮的可用状态，如果这个宏缺了，按钮可能处于禁用状态（灰色），看起来就像点击没反应。这个宏很多时候不是必须的，但一旦需要控制按钮置灰，没有它就会出现“明明ID对，也写了ON_COMMAND，按钮却是灰的”的情况。
工具栏自定义这个技术点，说穿了就是两个关键概念：一个是索引对应关系，一个是样式控制。图片也好，文字也罢，本质上都是在把数据正确地映射到按钮上，再把显示规则通过样式告诉系统。我个人做了几年MFC界面，踩过的坑里十个有八个都出在这两个地方。
最后再分享一个小技巧：调试工具栏时，可以把工具栏从停靠位置拖出来变成浮动窗（前提是创建时带上了CBRS_SIZE_DYNAMIC），这样布局是否合理一目了然，比在停靠状态下反复切换看效果要直观得多。如果新加按钮文字没出来，也别急着怀疑代码，先把窗口最大化再还原一次，排除是不是重绘没刷新的问题——有时候就是这么玄学，Windows界面开发，耐心和排查思路永远比记API重要。
本文还有配套的精品资源，点击获取
