简介这份资源面向使用 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的LoadBitmapSetButtonInfo适合按钮数量固定、图片规格统一的场景另一条是拿到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先缩放到目标尺寸再 AddCImage 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换成CMFCToolBarLoadBitmap换成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 确认图片和文字能同时显示再往项目里搬。因为工具栏这东西一旦图片列表和按钮索引对不上排查起来比业务逻辑还费时间。希望帮到你。本文还有配套的精品资源点击获取