OpenXLSX在MFC下读写Excel的实战指南（VS2019集成详解）

简介这是一份面向C/MFC开发者的OpenXLSX库集成示例解决在VS2019环境下无需依赖第三方工具即可读写ExcelXLSX文件的需求适合需将报表导出、数据导入等功能嵌入Windows桌面应用的开发者。资源共143个文件压缩包约128.69MB包含约50个hpp头文件与25个cpp源文件以及sln/vcxproj工程配置、编译生成的exe/lib/pdb、ipch/pch缓存、资源文件ico/rc等源码与工程结构完整便于直接对照学习。目前已有3681人学习下载热度较高。通过该示例可掌握OpenXLSX的核心API调用包括创建与读取工作簿、操作工作表、写入文本/数字/公式、设置单元格样式及插入图表并了解在MFC对话框中集成此库的常用方法可迁移到报表生成、数据批量处理等实际项目中。1. 项目概述与核心需求解构1.1 OpenXLSX解决的Excel处理痛点做C桌面开发的朋友应该都有过这种经历项目跑得好好的突然来了个需求——把界面上的数据导成Excel报表或者把Excel里的数据批量读进来。你用MFC对话框写了个上位机界面和通信逻辑都不是问题结果卡在Excel读写上。传统的做法无非几种第一调MFC里的OLE/COM接口去控制Excel进程。这个方案有个很恶心的问题——客户机器上必须装Office而且启动Excel实例非常慢动不动就卡住主线程一旦用户手滑弹个对话框出来程序就死在那里。第二用ODBC把.xlsx当数据库读但这只能对付简单的数据表格格式稍微复杂一点就抓瞎而且.xlsx的驱动在64位机器上配置起来也够折腾。OpenXLSX就是一个纯C的解决方案直接绕过Office进程手工解析Excel的XML文件结构读写.xlsx格式。GitHub上的开源项目MIT协议商用、集成到自己的MFC上位机里都没有版权包袱。最早我是在一个工控项目里接触到的当时要批量把采集到的设备参数导出成Excel报表给产线用用了OpenXLSX之后整个导出过程从“调COM卡顿半天”变成“毫秒级写完文件”体验完全不是一个量级。这个项目适合谁如果你在写MFC桌面应用、C工具软件需要把数据落到Excel或者从Excel读配置导入系统又没有装Office环境的权限OpenXLSX几乎是当前C生态里最省心的选择。VS2019编译、MFC集成这条路已经被验证得比较成熟了下面把整个过程拆开讲透。1.2 技术选型为什么在VS2019/MFC场景下押注OpenXLSX我不太喜欢一上来就无脑推荐某个库但Excel读写这块C生态的选择确实不多。我整理过一张对比表基本上每次给别人讲技术方案时都会摆出来方案格式支持依赖Office性能协议MFC集成难度调用COM/OLE.xls/.xlsx必须且需在客户端完整安装极慢启动Ole进程开销大无版权问题容易但体验差ODBC读Excel.xls/.xlsx(驱动支持有限)不一定但Driver配置麻烦一般无一般libxl.xls/.xlsx否快商业授权简单xlnt.xlsx否快BSD简单OpenXLSX.xlsx否快MIT简单xlnt其实也不错但它的API设计偏底层构造Cell类型、管理格式化样式时写起来非常啰嗦。OpenXLSX的上层API直接封装了Workbook、Worksheet、Cell这些概念你不需要知道XLSX内部是一堆XML和zip压缩包就能像操作数据库一样操作表格这对MFC这种以快速交付为目标的场景非常友好。另一个考量是编译兼容性。OpenXLSX的代码要求C17标准VS2019默认对C17的支持已经很稳不需要额外配什么奇奇怪怪的编译选项。它的依赖库pugixml、zlib也是通过CMake自动拉取只要网络畅通整个编译链路比较顺。后面我会详细讲编译环节的坑避免大家重走弯路。2. 环境准备与编译集成VS2019下的实操2.1 获取源码与依赖子模块OpenXLSX的源码托管在GitHub上搜索项目名就能找到。要注意的是这个仓库使用了子模块引用来管理第三方依赖所以不能直接点绿色按钮Download ZIP那样下载的包不包含依赖源码编译会报一堆找不到头文件的错。正确拉取源码的姿势是git clone --recursive https://github.com/troldal/OpenXLSX.git加--recursive这个参数会递归克隆所有子模块比如pugixml负责解析Excel内部XML、zlib负责解压zip包。如果你已经用普通方式克隆了也可以在项目目录下执行git submodule update --init --recursive这个命令会把缺失的子模块内容拉取回来。我见过不少人卡在这一步就是因为没有拉子模块VS2019编译时直接报“无法打开包含文件:pugixml.hpp”之类的错误。这其实是整个实验中最容易规避的问题提前做好就不折腾。2.2 CMake生成VS2019解决方案OpenXLSX官方推荐用CMake构建。先在机器上装好CMake3.15以上版本VS2019自带的CMake插件也可以。然后在OpenXLSX根目录下新建一个build文件夹执行cd OpenXLSX mkdir build cd build cmake .. -G Visual Studio 16 2019 -A x64-G指定生成VS2019的工程-A x64指定64位平台。这里强烈建议统一用x64尤其是MFC开发现在基本都是x64部署避免后面混用平台导致链接器报一堆LNK2019。CMake配置完成后打开生成的OpenXLSX.sln在解决方案里能看到OpenXLSX项目右键生成编译出静态库文件OpenXLSX.lib。如果你不需要跑测试可以在CMake时把-DOPENXLSX_BUILD_TESTSOFF加上能省掉一大部分编译时间。2.3 集成进MFC工程的两种方式MFC工程要使用OpenXLSX有两种路数各有利弊。我在实际项目里两种都用过按场景选择。第一种静态库引用方式。项目属性里配置好“VC目录→包含目录”加上OpenXLSX的sources目录依赖里把OpenXLSX.lib加进附加依赖项头文件里#include OpenXLSX.hpp就能用。这种方式适合把OpenXLSX当一个外部依赖库来管理工程结构干净升级库版本时只需要换lib文件。第二种直接把OpenXLSX的源代码文件加入MFC工程。这个做法看起来粗暴但调试时特别方便——你能直接跟到OpenXLSX源码内部看到哪个环节出了问题。MFC工程默认预编译头如果你遇到一堆莫名其妙的“unresolved external symbol”大概率是某些源文件没有正确参与编译。把OpenXLSX/sources目录下的.cpp文件全部添加到工程里同时确保每个文件都“使用预编译头”或“不使用预编译头”二选一别混着来。我自己的建议是正式项目用第一种学习调试用第二种。不管哪种字符集记得统一设成“使用Unicode字符集”这一点到MFC编码环节再展开。3. MFC应用集成与核心实现3.1 MFC对话框里读写Excel的完整流程先来看最核心的场景MFC对话框点一个“导出”按钮把表格控件里的数据写入Excel文件。我用一个精简但完整的示例来讲。假设你的对话框上有一个“导出”按钮ID为IDC_BTN_EXPORT对应的响应函数写法如下#include OpenXLSX.hpp #include fstream void CMyDialog::OnBnClickedBtnExport() { // 先用CFileDialog选择保存路径 CFileDialog dlg(FALSE, Lxlsx, LReport.xlsx, OFN_HIDEREADONLY | OFN_OVERWRITEPROMPT, LExcel 文件 (*.xlsx)|*.xlsx||, this); if (dlg.DoModal() ! IDOK) return; CString strPath dlg.GetPathName(); try { // 创建Excel文档对象 using namespace OpenXLSX; XLDocument doc; doc.create(strPath.operator LPCWSTR()); // MFC Unicode下CString可直接转为宽字符指针 auto wks doc.workbook().worksheet(Sheet1); // 写入表头 wks.cell(A1).value() 设备编号; wks.cell(B1).value() 采集温度; wks.cell(C1).value() 采集时间; // 模拟从列表控件读取数据简化用固定数组演示 for (int row 0; row m_list.GetItemCount(); row) { CString strDev m_list.GetItemText(row, 0); CString strTemp m_list.GetItemText(row, 1); CString strTime m_list.GetItemText(row, 2); int excelRow row 2; // 第1行是表头数据从第2行开始 wks.cell(excelRow, 1).value() CW2A(strDev.GetString()).m_psz; // UTF-8编码 wks.cell(excelRow, 2).value() CW2A(strTemp.GetString()).m_psz; wks.cell(excelRow, 3).value() CW2A(strTime.GetString()).m_psz; } doc.save(); doc.close(); AfxMessageBox(L导出成功); } catch (const std::exception ex) { CString strErr L导出异常; strErr CA2W(ex.what()).m_psz; AfxMessageBox(strErr); } }这个示例把OpenXLSX最核心的用法都涵盖了创建文档、获取工作表、写入单元格、保存关闭。几个关键点我展开说一下。doc.create(路径)是新建Excel文件就是“Create New Document”OpenXLSX内部会生成一个完整的.xlsx压缩包。不用担心文件重名覆盖问题它会自动覆盖。wks.cell(A1)可以通过列字母行号定位单元格也可以通过cell(row, col)行列索引定位两种方式我写代码时混着用。OpenXLSX用value()返回一个Proxy对象给这个Proxy赋值就能把值写进单元格字符串、数字、日期都可以它自己会判断类型。保存用doc.save()整个文档关闭前必须调用一次否则数据没落盘。3.2 字符串编码处理UTF-8与CString的无缝转换我在测试这个Demo时踩得最深的坑就是编码。MFC默认的Unicode工程里CString是宽字符UTF-16LE但OpenXLSX内部对字符串的处理是基于UTF-8的。直接写wks.cell(...).value() strPath.GetString()虽然编译能过因为OpenXLSX提供了宽字符重载但遇到中文时Excel打开会乱码。保险的做法是显式用UTF-8转换CW2A是MFC提供的宏把宽字符转成当前代码页的ANSI字符串。在使用OpenXLSX时配合CP_UTF8参数更准确wks.cell(A1).value() CW2A(strDev.GetString(), CP_UTF8).m_psz;读数据时反过来用CA2W把UTF-8转回宽字符std::string strValue wks.cell(B2).value().asstd::string(); CString strCell CA2W(strValue.c_str(), CP_UTF8).m_psz;这套转换逻辑是所有中文MFC项目都必须过的关。说句实在话90%的“写进去是乱码”“读出来是问号”都和编码转换没做对有关系。3.3 读取已有Excel数据到MFC列表控件除了导出另一个高频需求是把Excel数据导入到界面。比如程序跑起来后读取一份参数配置文件填充到表格控件里。这个场景和导出正好是逆向流程void CMyDialog::OnBnClickedBtnImport() { CFileDialog dlg(TRUE, Lxlsx, nullptr, OFN_FILEMUSTEXIST, LExcel 文件 (*.xlsx)|*.xlsx||, this); if (dlg.DoModal() ! IDOK) return; try { using namespace OpenXLSX; XLDocument doc; doc.open(dlg.GetPathName()); // 打开已有文件 auto wks doc.workbook().worksheet(Sheet1); m_list.DeleteAllItems(); uint32_t rowsTotal wks.rowCount(); for (uint32_t r 2; r rowsTotal; r) { std::string val1 wks.cell(r, 1).value().asstd::string(); std::string val2 wks.cell(r, 2).value().asstd::string(); CString str1 CA2W(val1.c_str(), CP_UTF8).m_psz; CString str2 CA2W(val2.c_str(), CP_UTF8).m_psz; int idx m_list.InsertItem(r - 2, str1); m_list.SetItemText(idx, 1, str2); } doc.close(); } catch (const std::exception ex) { AfxMessageBox(CA2W(ex.what(), CP_UTF8).m_psz); } }这里有个细节要留意rowCount()获取的是“实际有内容的最大行号”如果Excel表格中间某一行被删空了返回值可能比预期少。因此从数据源侧维护Excel时不要让表格中间出现整行空行否则导入程序会静默丢掉空行之后的数据。另外OpenXLSX读取单元格时如果值是数字用asstd::string()会报错或者拿到空字符串。这个时候需要先判断类型XLCellValue v wks.cell(r, c).value(); if (v.type() XLValueType::Float) double d v.asdouble(); else if (v.type() XLValueType::String) std::string s v.asstd::string();这手判断很实用。Excel里“数字写成文本”和“文本写成数字”两种单元格OpenXLSX会区分处理写代码时千万不能假设所有格子都是字符串。4. 常见问题与排查技巧实录4.1 编译期典型问题速查OpenXLSX本身质量很高但配合VS2019和MFC使用时你大概率会遇到下面几个报错我把常见原因和解决办法整理成表格错误现象可能原因解决办法C2039/C2065等编译错误pugixml找不到子模块未拉取git submodule update --init --recursiveLNK2019 无法解析的外部符号平台位数不一致或lib未链接确认x64/x86一致确认OpenXLSX.lib已加入附加依赖链接时大量重定义错误把OpenXLSX源文件重复加入了工程检查工程里是否同时引用了静态库又手动添加了.cpp编译慢到怀疑人生默认开启了测试项目CMake加-DOPENXLSX_BUILD_TESTSOFFC17特性不识别项目语言标准设置过旧项目属性→C/C→语言→C语言标准选C17其中LNK2019是最容易让人头皮发麻的。我一开始编译时忘了把库目录指对链接时一堆OpenXLSX函数解析不了。检查思路很简单先确认编译出的OpenXLSX.lib是哪年的哪个平台再确认MFC工程属性里的“平台”和它一致。Debug版配Release版库也会出现这种问题因为MSVC的Debug和Release运行时库是两套。4.2 运行期容易踩的坑文件被占用如果你用Excel打开了某个.xlsx再运行MFC程序往这个路径写文件OpenXLSX会抛异常提示“permission denied”。这是操作系统层面的文件锁和OpenXLSX无关。处理方式是捕获异常后提示用户“请先关闭正在打开的Excel”或者程序内部自动换个带时间戳的文件名。路径带中文MFC下路径用CFileDialog拿到的是宽字符传给OpenXLSX时建议确保使用宽字符串的API。OpenXLSX的open()、create()都有std::string和宽字符两种重载。直接用宽字符版本最省心不需要转ANSI反而不会出现中文路径解析失败的问题。读数值单元格时崩溃这是新手最容易踩的。OpenXLSX的value().asstd::string()在单元格存储的是数值时会抛出异常。我给一个判断模板写代码时直接套auto val wks.cell(r, c).value(); if (val.type() XLValueType::Integer) { int v val.asint(); } else if (val.type() XLValueType::Float) { double v val.asdouble(); } else if (val.type() XLValueType::String) { std::string v val.asstd::string(); }这套判断在读取生产环境Excel时非常重要因为用户填表格式千奇百怪你永远不知道某个“看起来是文本”的格子底层存的是什么类型。4.3 独家避坑经验最后分享几个OpenXLSX在MFC项目里用得久才能总结出来的习惯。第一用完XLDocument一定记得close()。OpenXLSX会持有文件句柄不关闭的话后续在同进程里再次操作同一路径会报错。MFC里如果频繁切换文档建议封装一个管理类用析构函数兜底close。第二save()和saveAs()的使用时机要分清。save()直接把内容写回当前打开的文件而saveAs()是另存为新文件。在桌面上位机里做“另存为”功能时用saveAs()比先close再create要稳能避免文件状态丢失。第三MFC界面线程里写Excel时如果数据量比较大比如两三万行建议把写Excel放到子线程里跑。OpenXLSX本身不阻塞UI但循环几万次写单元格还是需要点时间的一旦耗时超过几百毫秒界面就能感觉到卡顿。实际操作时可以用std::thread包一层通过PostMessage通知主线程完成状态这也是MFC里处理耗时任务的常见姿势。实测下来一个5万行、10列的表格OpenXLSX从创建到保存大约一秒钟左右相比COM方式动辄十几秒的等待优势相当明显。还有一点容易被忽略OpenXLSX只支持.xlsx格式不支持旧版的.xls。客户如果还在用Excel 97-2003的老格式需要先提醒他们另存为.xlsx或者程序里用其他库做格式转换。早期我在一个项目里接到的需求是“读Excel配置”结果客户给了一堆.xls文件OpenXLSX直接抛异常说不支持的格式。这个限制在使用前就要和需求方对齐避免开发到一半返工。总体来说OpenXLSX在VS2019MFC这套组合下是能稳定产出的。它把Excel文件当成一个.zip压缩包里面是一堆XML结构OpenXLSX帮你把解压、解析XML、修改内容、重新打包这一整套流程封装好了。相比之下我过去用COM方式控制Excel进程不但要操心Office版本兼容性还要处理进程残留问题每次用户强制关掉Excel后台就多一个僵尸进程非常头痛。如果你正准备在自己的MFC项目里集成Excel读写我的建议是不要犹豫直接从OpenXLSX开始把上面的示例代码跑通再按你的业务需求扩展。这套方案从编译到部署都是可控的至少在下一个Excel相关需求到来时你不会再为读写文件发愁了。本文还有配套的精品资源点击获取