企业官网建设流程全解析

做桌面端开发久了，难免会碰到读写Excel的需求。不管是导出报表、批量生成数据文件，还是把外部表格导入程序做处理，都是特别常见的场景。Qt 本身没有提供官方的 Excel 读写接口，所以大家通常都要自己选方案。而这个标题里的 QXlsx，可以说是目前 Qt 环境下读写 xlsx 文件绕不开的一个开源库。这篇内容我就围绕“QT + QXlsx 操作 Excel”这个主题，把从选型、集成，到写入、读取、样式、公式，再到各种坑的完整实战经验摊开讲清楚，适合正在做 Qt 桌面开发，并且被 Excel 导入导出困扰的朋友参考。

1. 选型之争：Qt 下操作 Excel 到底该用哪种方案

在敲定 QXlsx 之前，我其实也折腾过好几条路。先说结论：方案没有绝对的好坏，只看你的项目到底要跨平台还是要依赖 Windows。这一章节我把几个主流路子都盘点一下，顺便说说为什么最后选了 QXlsx。

1.1 四大主流方案横向对比

这里我分成四类：QAxObject 的 COM 方案、CSV 这种“伪 Excel”方案、纯 C 库 libxlsxwriter，以及今天的主角 QXlsx。给一张表格对比，后面逐个展开。

QAxObject 本质是 Qt 的 ActiveX 容器，在 Windows 上通过 COM 接口远程驱动 Office。这个方案最大的优点是可以完全控制 Excel 的能力，比如复杂的透视表、图表联动、宏处理，基本 Office 能做多少它就能做多少。缺点也很扎心：第一，离开 Windows 就玩不转；第二，目标机器必须有完整可用的 Office 或 WPS 环境；第三，COM 调用的效率感人。我早年做过一个批量导出上千行报表的模块，用 COM 逐行写单元格，跑完一次用户要盯着进度条等十秒以上，体验相当别扭。到今天，除非客户明确要求“必须在 Windows + Office 环境运行，而且需要最高级别的 Excel 自动化”，否则我不太推荐这条路。

CSV 方案是最容易想到的替代品。很多场景下我们其实只需要把数据导出来给用户看，CSV 用QTextStream写几行代码就够了，而且 Excel / WPS 打开 CSV 文件完全无障碍。但它的天花板就是“文本制表”，没有单元格样式、没有公式、没有多 Sheet。如果你的需求只是“把数据倒出去，长什么样无所谓”，CSV 完全够用，没必要上重型库。反过来，一旦客户说“要红字标出超标的行”，CSV 就当场歇菜。

libxlsxwriter 是纯 C 写的库，写入性能和功能都很强，支持样式、公式、图表，而且内存占用很友好。但它有一个天然短板：只写不读。如果你的应用只需单向导出，这是加分项；如果还要把用户填好的表格读回来解析，就必须再搭一套解析库，工程复杂度一下子就上去了。

1.2 为什么是 QXlsx：轻量、全功能、零依赖

QXlsx 这个库最初是一个开发者为了解决“Qt 应用要生成带样式的 Excel，但又不能要求客户装 Office”这个痛点而写的。它直接操作 xlsx 文件本身，而不是驱动 Excel 进程。xlsx 文件说白了是一个 zip 压缩包，里面装着一堆 XML 描述文档结构和数据，QXlsx 做的事情就是把 Qt 的数据结构和这些 XML 对应起来，对外暴露一套像Document、Format、Cell这样的简单 API。

选它有三个很实际的理由：

一是自定义程度高。它是纯开源库，源码直接能看，遇到问题可以自己改。

二是跨平台表现一致。Windows、Linux、macOS 上都是同一套代码，不用担心 COM 启动不了的问题。

三是能力覆盖均衡。写入、读取、样式、合并单元格、公式、多 Sheet、数据验证，这几个日常高频功能都有，尤其是读取能力，比 libxlsxwriter 这种只写库强出一大截。

当然，它也有自己的边界。QXlsx 对 Excel 里的对象比如 ActiveX 控件、较复杂的图表模板支持有限；处理超大文件（几十万行）时内存开销偏高。说白了它追求的是“够用、好用”，不是“弯道超车 Office 本尊”。

1.3 用前必须知道的能力边界

聊完优点，泼点冷水。我建议每个想用 QXlsx 的人都提前搞清楚它不能做什么，免得做到一半换方案：

• 不支持 xls 老格式，只支持 xlsx / xlsm 这部分现代格式。客户发来一堆 .xls 老文件，需要先在代码里或人工转换为 xlsx。
• 图表支持存在但不深度，能做基础柱状图、折线图、饼图，复杂的组合图表会比较吃力。
• 对 Excel 内置控件、VBA 宏这类内容不处理，xlsm 里的宏代码不会被读写。
• 超大 Excel 内存占用偏高，超过几十万行时读写速度会明显下降，需要考虑分 Sheet 或换 CSV。

2. 环境准备：获取源码并集成到 Qt 工程

先把 QXlsx 跑起来，这个环节其实比想象中简单。只要弄清楚三种集成方式，后面写代码就是调用 API 的事了。这里我详细过一遍。

2.1 获取 QXlsx 源码与仓库结构

我用的版本需要在 GitHub 上搜 QXlsx，下载源码包。实际上很多 Qt 项目里会直接以子模块方式引入，所以我拿到的是一个目录，常见结构如下：

QXlsx/ ├── QXlsx.pro ├── src/ │ ├── xlsxdocument.h │ ├── xlsxdocument.cpp │ ├── xlsxworkbook.h │ ├── xlsxworksheet.h │ ├── xlsxcell.h │ ├── xlsxformat.h │ ├── xlsxchartsheet.h │ └── ... ├── qxlsx.pri └── ...

核心逻辑就在src目录，而qxlsx.pri是给 Qt 工程引用的。你不需要逐个文件复制，pro 文件里一行include就能全带进来。有一点要注意：新版 QXlsx 基本兼容 Qt 5.12 及以上，我用 Qt 6 编译也完全没问题；如果你还在 Qt 5.9 这种老版本，建议选一个发布时间相近的旧 release，减少奇奇怪怪的编译报错。

2.2 三种集成方式，按项目场景选

方式一：直接把源码目录放进工程

这是最快的方式，特别适合自己写的独立小工具。把整个 QXlsx 目录丢到工程目录下，在.pro文件里写上：

include($$PWD/QXlsx/src/qxlsx.pri)

然后在任何用到 QXlsx 的源文件里包含头文件：

#include "xlsxdocument.h" #include "xlsxformat.h" #include "xlsxworksheet.h"

这种方式的好处是调试时可以直接跳进库源码，坏处是工程结构会带一份第三方源码，更新库时略麻烦。

注意：qxlsx.pri里默认会根据情况生成动态库或静态包含。如果想彻底静态，可以在.pro里加一行DEFINES += XLSX_NO_LIB。不同版本该宏可能略有差异，编译报错时再回头看 pri 内容即可。

方式二：独立编译成库，按需链接

如果你的业务系统比较庞大，QXlsx 是多个模块公共依赖，建议单独编译成一个静态库或动态库。参考命令如下：

qmake QXlsx.pro -spec win32-g++ CONFIG+=release mingw32-make

之后在业务工程里引入头文件路径和库文件路径即可。这种方式耦合最小，适合团队协作项目，缺点是修改 QXlsx 源码后需要重新编译库。

方式三：通过 Git 子模块引入

工程本身有 Git 管理的话，用git submodule或vcpkg拉取依赖是更规范的做法。子模块方式的好处是版本可控，团队其他人拉代码时一条命令同步，不用互相拷目录。缺点是要稍微熟悉 Git 子模块的基本操作。

我自己在正式项目里更偏向直接用方式一，因为 QXlsx 源码体积不大，而且偶尔出问题时直接进源码打断点最直观。依赖管理水平高、需要拉入自动构建流水线的团队建议走方式三。

2.3 最小可运行工程搭建记录

先搭一个能跑的空壳，验证集成有没有问题。新建一个 Qt Widgets 工程，pro 文件大概长这样：

QT += core gui greaterThan(QT_MAJOR_VERSION, 4): QT += widgets TARGET = ExcelDemo TEMPLATE = app DEFINES += QT_DEPRECATED_WARNINGS include($$PWD/QXlsx/src/qxlsx.pri) SOURCES += main.cpp

main.cpp里先写一个生成 Excel 的最小测试：

#include <QCoreApplication> #include "xlsxdocument.h" int main(int argc, char *argv[]) { QCoreApplication a(argc, argv); QXLSX::Document xlsx; xlsx.write(1, 1, "Hello QXlsx"); xlsx.saveAs("hello.xlsx"); return 0; }

编译运行后，工程目录下出现hello.xlsx，用 Excel 打开能看到左上角单元格写着“Hello QXlsx”。这个最小闭环一旦通了，就说明环境和集成没问题，后面就能放心往下写。

如果编译时报QObject相关错误，多半是 moc 没有把库里的自定义 QObject 类识别进来。优先确认.pro里是否成功include了 qxlsx.pri，以及有没有漏掉QT += core。

3. 核心实操：从数据写入到文件读取

环境通了，我们直接进入干货环节。由于 QXlsx 的 API 设计比较贴近 Excel 的“单元格 + 行 + 列 + 样式”概念，学起来很快，但几个细节位一旦理解到位，效率会完全不同。

3.1 创建文件并写入基础数据

所有操作都从QXLSX::Document开始。其中write(row, col, value)是最高频的方法，行列坐标从 1 开始计数，这跟 Excel 软件的显示是一致的。看一组例子：

#include "xlsxdocument.h" #include <QVariant> #include <QColor> void createBasicFile(const QString &filePath) { QXLSX::Document doc; doc.write(1, 1, "编号"); // A1 doc.write(1, 2, "名称"); // B1 doc.write(1, 3, "金额"); // C1 doc.write(2, 1, 1001); // 数字 doc.write(2, 2, "螺母"); // 文本 doc.write(2, 3, 12.5); // 浮点数 doc.write(3, 1, 1002); doc.write(3, 2, "螺栓"); doc.write(3, 3, 8.25); doc.saveAs(filePath); }

执行这段代码，得到一个三列三行的基础表格。这里介绍一下坐标系统：write(1, 1, ...)等价于write("A1", ...)，两种写法 QXlsx 都支持。当表格数据量比较大时，我习惯用行列号循环，因为循环里拼 A1、B2 这类字符串多少有点反人类。比如写一万行数据，列号变量加上去反而简单：

for (int row = 1; row <= 10000; ++row) { for (int col = 1; col <= 10; ++col) { doc.write(row, col, QString("R%1C%2").arg(row).arg(col)); } }

write自动根据 QVariant 的类型决定单元格类型：字符串就是文本、double就是数字、QDateTime就是日期时间。这点很省心，不需要你手动声明。

3.2 设置单元格样式：字体、颜色、边框与对齐

生成一个“素颜”表格只完成了第一步，实际项目里几乎都会要求把表头加粗、底色标蓝、那些超阈值的数据用红色标注。这些全靠QXLSX::Format类配合write的第四个参数完成。

直接看一个带样式的例子：

#include "xlsxdocument.h" #include "xlsxformat.h" #include <QColor> #include <QFont> void writeWithStyle() { QXLSX::Document doc; QXLSX::Format titleFormat; titleFormat.setFontSize(14); titleFormat.setFontColor(QColor("#FFFFFF")); titleFormat.setPatternBackgroundColor(QColor("#4472C4")); titleFormat.setHorizontalAlignment(QXLSX::Format::AlignHCenter); titleFormat.setVerticalAlignment(QXLSX::Format::AlignVCenter); QXLSX::Format headerFormat; headerFormat.setFontBold(true); headerFormat.setPatternBackgroundColor(QColor("#D9E1F2")); headerFormat.setBorder(QXLSX::BorderStyle::Thin); QXLSX::Format dangerFormat; dangerFormat.setFontColor(QColor("#FF0000")); dangerFormat.setBorder(QXLSX::BorderStyle::Thin); QXLSX::Format normalFormat; normalFormat.setBorder(QXLSX::BorderStyle::Thin); doc.write(1, 1, "库存预警表", titleFormat); doc.write(3, 1, "材料名", headerFormat); doc.write(3, 2, "安全库存", headerFormat); doc.write(3, 3, "当前库存", headerFormat); doc.write(4, 1, "轴承", normalFormat); doc.write(4, 2, 100, normalFormat); doc.write(4, 3, 45, dangerFormat, ); // 低库存标红 doc.saveAs("report.xlsx"); }

几个值得说的细节：

• 背景色用的是setPatternBackgroundColor，其他类似的 API 还有setForegroundColor之类，但真正用来铺底色的是这个。初学时我在这里翻过车：调了半天颜色没变化，一查才知道用的是图案背景。
• setBorder参数的QXLSX::BorderStyle::Thin表示细实线。边框其实是上下左右四种线的集合，如果只要下边框，可以调用setBorderStyle(QXLSX::BorderStyle::Thin)配合边框位置参数，日常表格用setBorder一把梭就够了。
• 创建 Format 对象有一定的成本，不要在一个大循环里反复new大量相同样式对象。建议在循环外建几个常用样式对象，循环里循环复用，从几十万行数据的角度看，这个优化收益非常可观。

3.3 合并单元格、行高列宽与公式

合并表头或添加统计行是报表的另一个高频需求。QXlsx 的mergeCells有两种传参方式：一种是传两个坐标点，另一种是直接传区域字符串。

void mergeAndFormula() { QXLSX::Document doc; // 表头跨列合并 doc.mergeCells(1, 1, 1, 4); doc.write(1, 1, "2025年度生产汇总表"); // 第二行写列标题 doc.write(2, 1, "车间"); doc.write(2, 2, "产量"); doc.write(2, 3, "废品数"); doc.write(2, 4, "合格率"); // 数据行 doc.write(3, 1, "A车间"); doc.write(3, 2, 1200); doc.write(3, 3, 20); doc.write(3, 4, QXLSX::Cell::Formula("=1-B3/C3")); doc.write(4, 1, "B车间"); doc.write(4, 2, 950); doc.write(4, 3, 15); doc.write(4, 4, QXLSX::Cell::Formula("=1-B4/C4")); // 合并后写入 doc.mergeCells("A6:C6"); doc.write(6, 1, "合计产量 = "); // 设置行高列宽 doc.setRowHeight(1, 30); doc.setColumnWidth(1, 12); doc.setColumnWidth(2, 14); doc.setColumnWidth(3, 14); doc.setColumnWidth(4, 14); doc.saveAs("summary.xlsx"); }

合并单元格时最容易踩的坑是：你合并的是一个区域，但写入数据时还是按区域左上角那个单元格的坐标写入。合并本身只是视觉上的合并，底层数据仍然存储在左上角单元格。如果你尝试往合并区域的其他单元格写值，会触发重复写入。另一个细节是行高和列宽的单位：QSS 中可能以为是像素，但 Excel 里行高和列宽有自己的单位体系，实际体验下来只要不是精确的排版要求，给个合适的数值就行，客户端会正常显示。

关于公式，建议使用QXLSX::Cell::Formula这个类型明确包裹公式字符串，而不是直接传"=1-B3/C3"。因为 QString 字符串被 QXlsx 默认当成纯文本处理，直接写"=xxx"有些版本会存成文本，打开 Excel 后不计算。用Cell::Formula在内部会明确标记为公式，计算结果由 Excel / WPS 负责。需要注意的是，QXlsx 本身不计算公式结果，公式的计算是在 Excel 或 WPS 打开文件时完成的。如果你想在代码里拿到计算结果，就要自己解析，或者让用户打开文件后用F9刷新。这一点在设计自动数据校验时要有预期。

3.4 读取现有 xlsx 文件：逐单元格读取与维度判断

读取是 QXlsx 的重要卖点。核心代码其实同样非常直白：Document构造时直接传入文件路径，再用read(row, col)读取单元格。因为单元格可能是字符串、数字、日期等任意类型，read返回的是QVariant，需要按需转成目标类型。

void loadAndPrint(const QString &filePath) { QXLSX::Document doc(filePath); if (!doc.load()) { // doc.load() 失败说明文件损坏或不是 xlsx return; } const QXLSX::CellRange range = doc.dimension(); int rowCount = range.rowCount(); int colCount = range.columnCount(); for (int row = 1; row <= rowCount; ++row) { QStringList rowTexts; for (int col = 1; col <= colCount; ++col) { QVariant value = doc.read(row, col); if (value.isValid()) { rowTexts << value.toString(); } else { rowTexts << QString(); } } qDebug() << rowTexts.join(" | "); } }

doc.dimension()返回的是整个表格的数据范围，简单理解就是有内容的行数和列数。读取时有两个注意点：

• dimension()返回的行列范围并不保证所有单元格都有值，中间空洞区域会返回QVariant无效值，上面代码里做了空值处理。
• 如果表格本身很大但中间很多空白行，用dimension()循环往往速度还挺快，但如果你要“只读符合条件的数据”，建议先读表头，再按条件分列筛选，别每读一次都重新解析整个文件。虽然它的封装让你可以反复read，但性能上不如一次迭代缓存。

如果只需要特定单元格的状态，还可以用doc.cellAt(row, col)判断单元格是否存在。这比直接read再判空更正统，因为它反映的是底层是否存在该坐标的节点信息。

3.5 大批量写入：从“能写”到“写得快”

开篇提到 COM 逐行写会慢，QXlsx 也不能说完全免疫性能问题，但至少比 COM 好很多。想让大批量写入又快又稳定，我按实践顺序总结三个技巧。

第一，减少不必要的Format创建。前面提过不赘述，每行都新建一个格式对象不只是内存压力，内部样式表的注册也会膨胀，最终文件体积会变大。

第二，尽量连续写入并提前规划行列。QXlsx 内部构建内存模型时会对行、列节点做缓存。如果写入顺序是跳跃的：先写(1,1)，再写(100,1)，然后写(2,1)，虽然逻辑上没错，但会频繁触发内部容器重排，拖慢速度。有大批量数据先按行序写，最自然。

第三，利用Worksheet对象避免频繁走Document层。很多场景是四周都固定调用doc.write(...)，实际上可以先拿到当前工作表：

QXLSX::Worksheet *sheet = doc.currentWorksheet(); for (int row = 1; row <= 50000; ++row) { for (int col = 1; col <= 20; ++col) { sheet->write(row, col, someValue); } }

粗测下来，Worksheet::write和Document::write相比少了一些额外的查找和锁定开销，数据量越大差距越明显。当然代码可读性会稍微打折，所以通常只在大批量写入时才这样写。

经验值补充：普通 xlsx 文件，如果一行只有十几个简单字段，QXlsx 单线程写五万行通常在几秒到十几秒之间，具体取决于 CPU 和磁盘。继续往上走就会明显吃内存，建议到十万行以上就开始思考分 Sheet 或数据分表。

4. 踩坑实录：QXlsx 使用中常见问题与排查

这个库整体稳定，但坑也不少。我把实际项目中遇到过的、以及同行高频讨论的问题整理成一组“踩坑记录”，按类型分开讲。

4.1 中文乱码：不是库的错，是文字编码的锅

最诡异的状况是：生成的 Excel 文件用代码读回来是正常的，但用 Excel / WPS 打开看到中文全是乱码。排查时多半是源码文件编码问题，而不是 QXlsx 的 bug。Qt 中QString用的是 UTF-16，内部转换没有问题，出乱码往往发生在两个环节：

一是源文件保存的编码与编译器预期不符。比如 Windows 下用 GBK 编码保存了带中文的 cpp 文件，编译器按系统默认代码页解析，字符串字面量进了内存就已经错了，QXlsx 接到的就是被破坏的QString。解决方法是统一源码文件为 UTF-8，并在.pro里加CONFIG += utf8_source。

二是拿到外部数据源的中文编码是 GBK 或 ANSI，没有转换成QString就写入。比如从某些老系统读出的字符串用的是本地编码，直接doc.write(row, col, rawData)，写入后自然会错。正确做法是先明确来源编码，再转换：

QString name = QString::fromLocal8Bit(rawBytes); // 按本地编码转 // 或者指定编码，比如 GBK： QTextCodec *codec = QTextCodec::codecForName("GBK"); QString name = codec->toUnicode(rawBytes);

我自己习惯统一把所有外部输入先转成QString，再进入业务层，后面不管写 Excel、写数据库、发网络报文都不会出现“局部乱码”。

4.2 文件被占用、保存失败排查

保存失败往往不是 QXlsx 的问题，而是文件被 Excel 或另一个进程占用，尤其多见于 Windows。saveAs直接返回bool，失败时绝大多数人第一反应是代码写错了。我的排查顺序是：

• 先确认目标路径可写，比如是不是写到了需要管理员权限的C:\Program Files下。
• 再确认文件没有在 Excel / WPS 里打开。Windows 下被占用文件强制覆盖通常会报权限错误。
• 再确认磁盘空间，这个较少见但也不能排除。
• 最后，如果文件路径包含中文或特殊字符，先尝试把路径改成纯英文。QXlsx 内部用 Qt 的QFile，但不同平台对本地编码处理策略有细微差别。开发阶段图省事，测试就放到QDir::currentPath()下，生产环境再抽象封装文件路径管理。

另外，Document对象如果之前已经加载过一个文件并做过修改，不调用save直接再次saveAs也能成功，但要注意多次保存会覆盖原文件。养成“加载后保存到新路径”的习惯对保护原数据很有帮助。

4.3 日期时间显示成数字：格式化问题

很多朋友第一次写入QDateTime得到的结果是 45000 这样的数字，瞬间傻眼。这其实是 xlsx 的日期本质：Excel 用“天数序列”存储日期时间。QXlsx 根据 QVariant 识别为日期后，只是帮你在底层写了序列值，并没有自动绑定显示格式。显示成数字还是日期，取决于单元格的 number format。

解决办法是在写入的格式里指定日期格式串：

QXLSX::Format dateFormat; dateFormat.setNumberFormat("yyyy-mm-dd hh:mm:ss"); QDateTime now = QDateTime::currentDateTime(); doc.write(1, 1, now, dateFormat);

这样 Excel 打开看到的就是被格式化的日期而非一串数字。还有一个小问题：如果你希望日期真正按文本格式写入，而不是日期类型，请直接toString("yyyy-MM-dd hh:mm:ss")转成 QString 写入，但这样就不能在 Excel 里做日期计算了。具体场景具体选，没有万能的写法。

4.4 编译和链接报错的典型场景

集成 QXlsx 时，我遇到最典型的编译错误分这三类。

第一类是 C++11 / C++14 标准编译不过。新版 QXlsx 使用了不少现代化 C++ 特性，一旦编译器版本过老就会报语法错误。Qt 5.12 以后默认已经打开了所需标准，实在不行在.pro里加CONFIG += c++14。

第二类是 qxlsx.pri 在不同 Qt 版本下的宏定义差异。例如某些版本要求DEFINES += XLSX_NO_LIB，有些版本又通过CONFIG控制生成动态库还是静态合并。报错信息如果含糊不清，直接打开qxlsx.pri跟踪条件分支，通常几分钟就能定位。

第三类是缺少头文件依赖。QXlsx 内部使用了QZipReader等 Qt 的私有或扩展类，在 Qt 6 下有些类被移动或改名。遇到“头文件找不到”的情况，去 src 里看实际 include 的头文件名，或者检查 qmake 的QT += core gui是否完整。缺少QT += gui是最常见的原因，因为 QXlsx 中很多绘制相关的类需要 gui 模块。

4.5 常见问题速查表

最后把零碎的坑汇总成表格，方便调试时快速定位。

其中“跨线程访问”我特别提醒一句：Document不是线程安全的。你可以在一个线程里写数据，另一个线程里写另一个文件，但不能两个线程同时操作同一个 Document 对象。为了实现“界面不卡顿生成报表”，常规做法是让整个生成过程跑在QtConcurrent::run或QRunnable里，期间不要用任何 UI 线程里的 Document 实例。

5. 进阶能力：多 Sheet、图表与更多写法

基础读写掌握以后，很多需求就自然而然要往更高层走。这里挑几个我实际用到过、也推荐大家去试的功能点。

5.1 多 Sheet 管理：报表最常见的结构

导出一份汇总报表，通常要有“汇总页”和“明细页”，这就绕不开多 Sheet。QXlsx 对多 Sheet 的支持很直观：

void multiSheetDemo() { QXLSX::Document doc; // 默认第一个 Sheet，可以改名字 doc.currentWorksheet()->setSheetName("汇总"); doc.write(1, 1, "总览数据"); // 新增第二个 Sheet doc.addSheet("明细"); doc.write(1, 1, "明细数据"); // 新增第三个 Sheet doc.addSheet("统计图"); doc.selectSheet("统计图"); doc.write(1, 1, "图表数据"); // 来回切换写入 doc.selectSheet("汇总"); doc.write(2, 1, "回到汇总页"); doc.saveAs("multiSheet.xlsx"); }

关于 Sheet 名，有两个必须注意的点。一是 Sheet 名不能为空、不能重复。二是 Sheet 名内不能出现[]:*?/\\这些字符，否则 Excel 本身不允许创建。加防御性检查总比用户打开文件报错要强。

addSheet之后当前 Sheet 会自动切到新添加的 Sheet 上，如果你想回到之前的 Sheet，必须显式selectSheet。很多新手在这里迷路：明明在第一个 Sheet 写了数据，第二个 Sheet 一 add，后面的写入全跑到了新 Sheet，排错半天才发现是当前工作表切换了。

5.2 图表与图片：让报表有展示力

QXlsx 的图表能力不算强，但我平时用到的基础图表还够。它内部是基于QtCharts或自绘 XML 描述来生成图表节点，实际写一个简单柱状图大致是这样的流程：

#include "xlsxdocument.h" #include "xlsxchart.h" void createChartDemo() { QXLSX::Document doc; doc.write(1, 1, "月份"); doc.write(1, 2, "销量"); doc.write(2, 1, "1月"); doc.write(2, 2, 120); doc.write(3, 1, "2月"); doc.write(3, 2, 135); doc.write(4, 1, "3月"); doc.write(4, 2, 98); QXLSX::Chart *chart = doc.insertChart(6, 1, QXLSX::Chart::BarChart); chart->addSeries(QXLSX::CellRange("B2:B4"), QXLSX::CellRange("A2:A4")); doc.saveAs("chart.xlsx"); }

图标这块，每个 QXlsx 版本 API 都可能有小差异，编译报错时直接看版本示例目录里的 demo 最快。说句实在话，如果对图表排名有很高要求，反而建议导出数据后用专业报表工具处理，或者从 Excel 模板中编辑图表预留位。毕竟代码生成一个漂亮的交互式图表，学习成本并不比让使用者自己在 Excel 里拖一拖少多少。

插入图片倒是非常方便，一句话就能把程序里的图片资源写入单元格附近：

doc.insertImage(2, 2, "logo.png");

需要注意图片路径编码问题同样存在，中文路径建议包装后做一个QFile::exists检查，避免文件没找到时程序默默跳过。

5.3 从 QXlsx 起步：更完整的 Excel 处理闭环

如果项目对 Excel 处理的要求持续变高，比如需要动态数据验证、条件格式、透视表，我认为不一定要死磕 QXlsx。它适合“轻量、跨平台、快速集成”的场景，但如果需求已经到达“我要像 Office 一样操作 Excel”，那就该考虑换思路：

• 服务端程序可以用 Python 的 openpyxl 或 pandas 形成独立的报表服务，Qt 只管显示。
• Windows 专用系统再考虑 QAxObject 直接连 Office。
• 如果只是读数据，也可以用QXlsx读出来后配合 QTableView 渲染，避免重造轮子。

应用架构设计的本质是选合适边界。QXlsx 是那个“刚刚好”的库，它不会替你解决所有 Excel 自动化问题，但能在 80% 的场景把活干得干净利落。

写在最后

说点个人体会。我第一次用 QXlsx 的时候，总觉得一个操作 Excel 的库应该很复杂，结果从集成到跑通只花了十几分钟。真正花时间的是各类边角问题，比如日期序列、合并单元格的存储、不同版本 API 差异。之后在几个实际项目里，我用它做过生产报表导出、设备参数导入解析、临时数据交换，整体都稳定可靠，唯一的悟道是：凡是涉及到文件落盘的，务必做好备份策略。

最后再分享一个小技巧：排查任何编码、格式、丢失问题时，xlsx 本质是个 zip 包，把生成的 xlsx 后缀改成 zip 解压，用文本编辑器直接看xl/worksheets/sheet1.xml和xl/styles.xml。这样你能直观看到 QXlsx 究竟往 XML 里写了什么，很多谜团一下就解开了。这个库文档不算丰富，但“文件即真相”，多拆几次包，你就比很多只会调 API 的开发者懂得更多。