简介：这份资源面向使用 MFC 开发 Windows 桌面程序的初中级开发者，聚焦 CToolBar 工具栏的自定义图片与文字显示问题。包内共 24 个文件，以 h 头文件、cpp 源文件为主，辅以 ico 图标、rc 资源脚本、vcxproj 工程文件及一份 ReadMe 说明文档，压缩包约 324KB，可直接用 Visual Studio 打开编译运行。示例项目 TimeClient 演示了工具栏的创建与初始化、位图资源加载、按钮图像索引与文字样式设置，以及停靠与浮动状态的切换处理，并附带工具栏图片素材与代码说明，方便对照修改。已有 1684 人学习下载，适合希望快速掌握 MFC 工具栏定制、减少重复摸索的开发者参考借鉴。

1. 从一张糊掉的工具栏截图说起：CToolBar 到底能改到什么程度

接手一个老 MFC 项目时，最常被吐槽的往往不是业务逻辑，而是顶上那条灰扑扑的工具栏——按钮是 16 色位图，文字要么没有，要么挤成一团。产品经理丢过来一张设计稿，要求按钮带彩色图标、图标下面配文字、鼠标悬停还要变色。你打开资源编辑器，发现CToolBar默认只认 4bit 的TOOLBAR资源，想塞一张 32 位带透明通道的 PNG 进去，它直接给你显示成黑块。

这就是MFC CToolBar自定义图片及文字要解决的核心问题：让工具栏摆脱资源编辑器的限制，用代码动态加载图片、设置文字、控制按钮状态。它适合两类人——一类是维护 MFC 遗留系统、需要在不重写 UI 框架的前提下做视觉升级的工程师；另一类是刚接触 MFC、想搞懂CToolBar、CToolBarCtrl、CMFCToolBar三者关系的开发者。这篇笔记按「先跑通最小 Demo，再拆图片和文字两条线，最后处理踩坑」的顺序展开，代码可以直接抄进你的MainFrm.cpp里验证。

2. 最小可运行 Demo：从资源编辑器到代码动态创建

2.1 先搞清楚 CToolBar 和 CToolBarCtrl 的分工

很多人第一次改工具栏会懵：到底该操作CToolBar还是CToolBarCtrl？简单说，CToolBar是 MFC 对工具栏的封装类，负责和CFrameWnd的停靠布局打交道；CToolBarCtrl是它内部持有的原生控件包装，真正管按钮的增删改查。你调用CToolBar::SetButtonInfo，底层转手就调了CToolBarCtrl的对应方法。

所以自定义图片和文字时，有两条路：一条是继续用CToolBar的LoadBitmap+SetButtonInfo，适合按钮数量固定、图片规格统一的场景；另一条是拿到CToolBarCtrl句柄，用AddButtons、SetImageList、SetButtonText精细控制，适合动态增删按钮。我一般先用第一条路跑通，遇到图片规格不统一再切第二条。

2.2 一个能跑的最小工程结构

假设你已经用 VS 建了一个 MFC 单文档项目，主框架类叫CMainFrame。默认情况下工具栏资源 ID 是IDR_MAINFRAME，在CMainFrame::OnCreate里通过EnableDocking和DockControlBar挂上去。我们要做的第一件事，是把它改成不依赖资源编辑器里的 TOOLBAR 资源。

// MainFrm.h 中声明成员 CToolBar m_wndToolBar; CImageList m_imgList; // 自己维护图片列表，方便后续替换 // MainFrm.cpp 的 OnCreate 中 int CMainFrame::OnCreate(LPCREATESTRUCT lpCreateStruct) { if (CFrameWnd::OnCreate(lpCreateStruct) == -1) return -1; // 1. 创建工具栏窗口，指定风格 if (!m_wndToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE | CBRS_TOP | CBRS_GRIPPER | CBRS_TOOLTIPS) || !m_wndToolBar.LoadBitmap(IDR_MAINFRAME)) { TRACE0("Failed to create toolbar\n"); return -1; } // 2. 设置按钮文字（关键：先让按钮支持文字） m_wndToolBar.SetButtonText(0, _T("新建")); m_wndToolBar.SetButtonText(1, _T("打开")); m_wndToolBar.SetButtonText(2, _T("保存")); // 3. 让按钮同时显示图片和文字 m_wndToolBar.SetSizes(CSize(48, 48), CSize(24, 24)); // 4. 停靠并显示 m_wndToolBar.EnableDocking(CBRS_ALIGN_ANY); EnableDocking(CBRS_ALIGN_ANY); DockControlBar(&m_wndToolBar); return 0; }

这段代码的逻辑说明：CreateEx的第二个参数TBSTYLE_FLAT决定按钮是扁平风格，配合CBRS_TOOLTIPS才有悬停提示。LoadBitmap加载的是资源里的位图条，每个按钮占 16x15 像素（默认）。SetButtonText必须在SetSizes之前调用，否则文字可能被裁掉。SetSizes第一个参数是按钮整体尺寸，第二个是图片尺寸——图片尺寸必须小于按钮尺寸，否则文字没地方放。

参数怎么改：如果你想让按钮更大，把CSize(48,48)改成CSize(64,64)，同时图片尺寸也要等比放大。注意LoadBitmap加载的位图总宽度必须是单张图片宽度的整数倍，否则后面的按钮会错位。

2.3 验证是否生效的三个检查点

跑起来之后，如果工具栏还是老样子，按顺序查这三处：第一，确认IDR_MAINFRAME这个位图资源确实存在且宽度是 16 的倍数；第二，确认SetButtonText的索引没有越界，按钮数量由位图宽度除以 16 决定；第三，确认没有在OnCreate之后又调用了LoadBitmap覆盖掉文字设置。常见翻车场景是：你在OnCreate里设了文字，但CFrameWnd的OnUpdateFrameTitle之类的逻辑又把工具栏重建了一遍。

3. 图片自定义：从 4bit 位图到 32 位 PNG 的完整替换方案

3.1 为什么 LoadBitmap 加载 PNG 会变黑

CToolBar::LoadBitmap内部调用的是CBitmap::LoadBitmap，它只认.bmp资源，而且对颜色深度有要求——通常是 4bit 或 8bit。你如果把一张 32 位带 Alpha 通道的 PNG 直接塞进资源，MFC 会把它当成 DIB 处理，透明区域变成黑色，边缘还有锯齿。这是最典型的「玄学」问题：图片在 PS 里好好的，进程序就糊了。

要支持 32 位图片，必须绕开LoadBitmap，改用CImageList配合CToolBarCtrl::SetImageList。CImageList支持ILC_COLOR32标志，能保留 Alpha 通道。具体做法是：先用CImage加载 PNG 文件（不是资源），然后逐张Add到CImageList里。

3.2 用 CImageList 替换工具栏图片列表

// 假设你有三张 32x32 的 PNG 文件放在 exe 同目录 void CMainFrame::SetupToolBarImages() { // 1. 创建支持 32 位色的图像列表 m_imgList.Create(32, 32, ILC_COLOR32 | ILC_MASK, 0, 3); const TCHAR* files[] = { _T("new.png"), _T("open.png"), _T("save.png") }; for (int i = 0; i < 3; ++i) { CImage img; HRESULT hr = img.Load(files[i]); if (FAILED(hr)) { TRACE(_T("Load %s failed\n"), files[i]); continue; } // 2. 转成 HBITMAP 并加入列表，第二个参数是掩码色 HBITMAP hBmp = (HBITMAP)img.Detach(); m_imgList.Add(CBitmap::FromHandle(hBmp), RGB(255, 0, 255)); ::DeleteObject(hBmp); } // 3. 把图像列表交给工具栏控件 m_wndToolBar.GetToolBarCtrl().SetImageList(&m_imgList); // 4. 重新设置按钮尺寸，图片 32x32，按钮留出文字空间 m_wndToolBar.SetSizes(CSize(56, 56), CSize(32, 32)); }

逻辑说明：CImageList::Create的第三个参数ILC_COLOR32是关键，少了它 Alpha 通道就丢了。CImage::Detach把内部 HBITMAP 所有权交出来，避免析构时重复释放。SetImageList之后，工具栏会按图像列表里的顺序给按钮分配图片，索引从 0 开始。SetSizes必须在SetImageList之后调用，否则按钮尺寸不会刷新。

参数说明：ILC_MASK表示使用掩码色，如果你确定 PNG 自带 Alpha，可以去掉它。RGB(255,0,255)是掩码色，选一个图片里绝对不会出现的颜色。SetSizes的按钮高度 56 是给文字留的空间，如果你不需要文字，可以改成 40。

3.3 图片尺寸不统一时的处理策略

实际项目里经常遇到图标大小不一，比如有的 24x24，有的 32x32。CImageList要求所有图片尺寸一致，所以要么在加载前统一缩放，要么用多个图像列表切换。我一般用CImage::StretchBlt先缩放到目标尺寸再 Add：

CImage scaled; scaled.Create(32, 32, 32); img.StretchBlt(scaled.GetDC(), 0, 0, 32, 32, SRCCOPY); scaled.ReleaseDC();

注意StretchBlt对透明通道的处理不完美，缩放后边缘可能发灰。更稳妥的做法是让 UI 设计师直接输出统一尺寸的 PNG，省掉运行时代码缩放。

4. 文字自定义：按钮文字、提示文字与动态更新的边界

4.1 SetButtonText 的三个隐藏约束

CToolBar::SetButtonText看起来简单，但它有三个约束：第一，按钮必须已经存在，索引不能超过GetCount()；第二，文字长度超过按钮宽度会被截断，不会自动换行；第三，如果按钮风格里没有TBBS_TEXT，文字可能不显示。所以正确顺序是：先SetButtonStyle加上TBBS_TEXT，再SetButtonText，最后SetSizes调整尺寸。

// 给第 0 个按钮设置文字和风格 UINT nID, nStyle; int nImage; m_wndToolBar.GetButtonInfo(0, nID, nStyle, nImage); nStyle |= TBBS_TEXT; // 关键：允许显示文字 m_wndToolBar.SetButtonInfo(0, nID, nStyle, nImage); m_wndToolBar.SetButtonText(0, _T("新建文件"));

逻辑说明：GetButtonInfo取出当前风格，按位或上TBBS_TEXT再写回去。SetButtonInfo的第四个参数是图片索引，传 -1 表示不改变图片。这样操作后，按钮会同时显示图片和文字，文字默认在图片下方。

4.2 提示文字和状态栏联动

工具栏的悬停提示（ToolTip）和状态栏提示是两套机制。ToolTip 由CBRS_TOOLTIPS风格控制，文字来自按钮的TBBS_TEXT或者资源里的字符串表。状态栏提示需要你在CMainFrame里处理ON_UPDATE_COMMAND_UI或者重写GetMessageString。常见做法是：按钮 ID 对应的字符串资源里写两段，用\n分隔，第一段是 ToolTip，第二段是状态栏文字。

// 在 .rc 文件的 STRINGTABLE 中 IDS_BTN_NEW "新建文件\n创建一个新的文档"

这样鼠标悬停显示「新建文件」，移到按钮上时状态栏显示「创建一个新的文档」。如果你用SetButtonText动态改了文字，ToolTip 会跟着变，但状态栏文字还是走字符串表，两者不同步是正常的。

4.3 动态更新文字时的重绘问题

有些场景需要根据状态改按钮文字，比如「开始」变成「停止」。直接调SetButtonText后，按钮区域可能不会立即重绘，出现文字重叠。解决办法是调完SetButtonText后手动触发重绘：

m_wndToolBar.SetButtonText(3, _T("停止")); m_wndToolBar.GetToolBarCtrl().Invalidate(); m_wndToolBar.GetToolBarCtrl().UpdateWindow();

注意不要用m_wndToolBar.Invalidate()，那是整个工具栏窗口重绘，效率低。用GetToolBarCtrl()拿到内部控件再刷新，只重绘按钮区域。

5. 避坑与排查：五个让工具栏显示异常的典型场景

5.1 按钮图片显示为黑块或全白

现象：加载 PNG 后按钮区域一片黑，或者全白没有图案。原因：CImageList创建时没加ILC_COLOR32，或者CImage::Load失败但没检查返回值。解决：在Create里显式加上ILC_COLOR32，并在Load后判断FAILED(hr)，失败时用TRACE输出文件名。另外确认 PNG 文件路径是绝对路径或相对于工作目录，不是相对于 exe 目录。

5.2 文字被图片挤掉不显示

现象：调了SetButtonText，但按钮上只有图片没有文字。原因：SetSizes的按钮尺寸太小，图片占满了整个按钮，文字没有绘制空间。解决：把按钮高度设为图片高度加 16 像素以上，比如图片 32x32，按钮至少 48x48。同时确认按钮风格里有TBBS_TEXT。

5.3 工具栏停靠后按钮错位

现象：工具栏浮动时正常，一停靠到框架上按钮就挤在一起或间距异常。原因：SetSizes在停靠后被框架的布局逻辑覆盖了。解决：在OnCreate里设置完尺寸后，再调一次m_wndToolBar.SetWindowPos强制刷新，或者重写CMainFrame::RecalcLayout，在CFrameWnd::RecalcLayout之后重新SetSizes。

5.4 高 DPI 下图片模糊

现象：在 125% 或 150% 缩放的显示器上，工具栏图片被拉伸得模糊。原因：CImageList里的图片是固定像素尺寸，系统缩放时直接拉伸。解决：根据GetDpiForWindow获取当前 DPI，按比例加载更大的图片，或者准备两套图片列表在 DPI 变化时切换。MFC 较新版本可以用AFX_GLOBAL_DATA::UpdateFonts配合处理。

5.5 按钮点击无响应

现象：图片和文字都正常，但点击按钮没反应。原因：按钮 ID 没有对应的ON_COMMAND消息映射，或者工具栏的CBRS_TOOLTIPS风格干扰了点击。解决：检查MainFrm.cpp的消息映射表里是否有ON_COMMAND(ID_BTN_NEW, &CMainFrame::OnBtnNew)，并确认按钮 ID 不是 0。如果用了SetButtonInfo改了 ID，消息映射也要同步改。

6. 进阶技巧：用 CMFCToolBar 做现代化外观与状态持久化

如果你用的是 VS2008 之后的 MFC 版本，CMFCToolBar比CToolBar更适合做现代化工具栏。它原生支持 32 位图片、文字标签、下拉按钮、自定义颜色，还能把工具栏状态存到注册表。迁移成本不高：把CToolBar换成CMFCToolBar，LoadBitmap换成LoadToolBar或者SetImages。

// 用 CMFCToolBar 加载 32 位图片 CMFCToolBar m_wndToolBar; if (!m_wndToolBar.CreateEx(this, TBSTYLE_FLAT, WS_CHILD | WS_VISIBLE | CBRS_TOP | CBRS_GRIPPER) || !m_wndToolBar.LoadToolBar(IDR_MAINFRAME)) { return -1; } // 设置文字标签 m_wndToolBar.SetButtonText(0, _T("新建")); m_wndToolBar.SetButtonText(1, _T("打开")); // 开启文字显示 m_wndToolBar.SetToolBarBtnText(0, _T("新建"), TRUE, FALSE); m_wndToolBar.SetToolBarBtnText(1, _T("打开"), TRUE, FALSE); // 状态持久化：保存到注册表 m_wndToolBar.EnableCustomizeButton(TRUE, ID_VIEW_CUSTOMIZE, _T("自定义"));

SetToolBarBtnText的第二个参数是文字，第三个参数TRUE表示显示文字，第四个参数FALSE表示文字在图片右侧（TRUE则在下方）。EnableCustomizeButton会加一个下拉箭头，让用户自己增删按钮，状态自动存到注册表HKEY_CURRENT_USER\Software\你的公司\你的应用下。

验证方法：运行程序，拖动工具栏到不同位置，关闭再打开，看按钮布局是否恢复。如果没恢复，检查CMFCToolBar的LoadState和SaveState是否在CMainFrame的OnClose和OnCreate里被调用。我一般会在OnCreate末尾加m_wndToolBar.LoadState(_T("ToolBar"))，在OnClose里加m_wndToolBar.SaveState(_T("ToolBar"))。

从那以后我每次改工具栏，都强制先跑一遍最小 Demo 确认图片和文字能同时显示，再往项目里搬。因为工具栏这东西，一旦图片列表和按钮索引对不上，排查起来比业务逻辑还费时间。希望帮到你。

本文还有配套的精品资源，点击获取