简介：这是一份面向 Qt 开发者的 Excel 读取与 TableWidget 展示示例，围绕可复用的读取封装和配套演示展开，适合正在使用 Qt5、需要把 Excel 数据导入表格界面的初、中级开发者参考，也可作为小型工具原型的基础素材。压缩包以 rar 形式提供，共 8 个文件，体积约 8KB，包含 3 个 cpp 与 2 个 h 源文件，承担读取逻辑、引擎封装和界面类实现，另有 ui 界面文件、pro 工程配置及 user 本地配置，便于直接打开工程对照理解模块组织。目前已有 3000 人学习，说明其在 Qt 表格数据导入这一常见场景中具备一定参考价值。读者可以从中梳理 Excel 引擎封装与界面调用的分工，观察数据读取、表格填充、工程配置之间的配合，理解可运行示例的职责拆分，并以此为骨架改造成自己的数据导入模块，减少从零搭建示例与排查基础配置问题的时间。
1. Qt 读 Excel 显示到 TableWidget：封装一次，后面每个界面都省事
手上维护一个 Qt 桌面工具，现场同事导出的报表多是.xlsx，交付时最常被问的一句就是“能不能直接把表格贴进界面看”。第一次我直接用QAxObject走 COM 调 Excel，本机装没装 Office、32/64 位组件是否匹配、进程残留不退出，问题一个接一个。后来把这套流程抽成一个薄封装：读表、转成二维数据、按列宽刷进QTableWidget，界面层只管调用。这个 demo 解决的就是“Qt 里读 Excel 并显示到表格控件”这一件事，适合正在做配置管理、报表查看、数据导出校验类小工具的开发者，新手能照着跑通，熟手能看清 COM 方案的边界在哪。
2. 方案选型：QAxObject 走 COM 与第三方库的取舍
2.1 为什么先用 QAxObject 把链路跑通
QAxObject是 Qt 对 ActiveX 的封装，Windows 平台下能直接驱动本机安装的 Excel 应用对象，本质上写的是和 VBA 同一套对象模型：Application → Workbooks → Worksheets → Range。它的好处是不引入任何第三方依赖，工程里只要有axcontainer模块就能编译，读单元格的值、取已用区域行列数、处理公式计算结果都现成。
代价也很明确：必须有 Excel 或兼容的 Office 套件装在运行机器上，进程模型是跨进程 COM 调用，每一次取值都走一遍接口封送，行列上千之后性能会明显往下掉。这也是我把它定位成“先把链路跑通、再谈优化”的原因——对内网固定几台办公机、单表几百行的场景完全够用；对无 Office 环境或需要批量导入几十个文件的场景，就得考虑切第三方解析库。
常见做法是准备两条路：COM 路线负责“和本机 Excel 行为一致”，包括公式、日期、合并单元格；第三方库路线（读 xlsx 的纯 C++ 库一类）负责“不依赖 Office、速度可控”。封装层如果把接口设计成只吐二维字符串数组，上层界面就不关心底下走哪条，这也是我后面写ExcelReader的动机。
2.2 工程配置：axcontainer 模块和头文件前置
Qt 的 ActiveX 支持不是默认开的，.pro里要显式加模块；CMake 工程则是找组件再链接。MSVC 与 MinGW 的差别要留意：MinGW 下的 ActiveX 支持一直被社区诟病不稳定，我一般只在 MSVC 套件上启用这条路线。
# .pro 片段：启用 ActiveX 容器模块 QT += core gui axcontainer CONFIG += c++17# CMakeLists.txt 片段 find_package(Qt6 COMPONENTS Core Gui Widgets AxContainer REQUIRED) target_link_libraries(YourApp PRIVATE Qt6::Core Qt6::Gui Qt6::Widgets Qt6::AxContainer)第一段是 qmake 写法，axcontainer是模块名，缺了它QAxObject的头文件根本找不到；第二段是 CMake 写法，Qt6 里组件名是AxContainer，大小写敏感。CONFIG += c++17不是必须的，但封装里用到QVector<QVector<QVariant>>这类容器时，统一标准能少踩编译器差异的坑。
注意：
QAxObject相关头文件在部分 Qt 版本里需要#include <QAxObject>且依赖windows.h的包含顺序，若出现类型重定义报错，把 Qt 头放在系统头之前通常能解。
2.3 对象模型映射：从 Workbook 到 Cell 的取值路径
Excel 的 COM 对象是树状的，读一个单元格要一路走下去：Application拿到Workbooks，Workbooks打开具体文件得到Workbook，Workbook里取Worksheets的第 N 项，再querySubObject("Range(...)")定位区域。封装的价值就在于把这串路径固定下来，并且保证异常分支也能正确释放。
几个关键属性值得先记住：UsedRange返回已使用区域，用它的Rows->Count和Columns->Count拿有效行列；Value属性一次取整个区域会返回QVariant包裹的二维数组，逐格取值则是Range("A1").Value。前者快一个数量级，代价是对混合类型区域的处理要自己做兼容。
日期是另一个高频坑：Excel 内部把日期存成序列号，Value取回来是double，只有Text属性才拿到显示文本。封装里我统一走Value再按业务判断是否按日期格式化，避免Text受列宽截断影响出现###。
3. 封装实现：ExcelReader 的接口设计与批量取值
3.1 对外只暴露三个方法
封装类我命名为ExcelReader，对外接口压到最小：open打开文件并缓存工作表名列表，sheetNames供界面下拉选择，readSheet按表名读回二维QVariant数据。这样界面层不需要知道 COM 的任何细节，切换数据源也只是换一个 reader 实现。
// excelreader.h #pragma once #include <QString> #include <QStringList> #include <QVector> #include <QVariant> class ExcelReader { public: ExcelReader(); ~ExcelReader(); // 打开文件，成功返回 true，并在内部缓存工作表名 bool open(const QString &filePath); // 返回当前文件的所有工作表名 QStringList sheetNames() const; // 读取指定工作表，返回 [行][列] 的二维数据 QVector<QVector<QVariant>> readSheet(const QString &sheetName, QString *error = nullptr); void close(); private: class Private; Private *d; };这里用了 PIMPL 惯用法，Private里才持有QAxObject*。原因很实际：QAxObject的头会带进 Windows 类型定义，如果直接写在头文件里，任何包含excelreader.h的界面类都会被牵连，编译时间和宏冲突都会变多。用前置声明隔开之后，界面层包含这个头几乎没有成本，后面真要换成第三方解析库，也只需要改Private的实现，调用方一行不动。
readSheet的错误通过出参QString *error回传而不是抛异常，是因为 Qt 工程里跨模块抛异常的处理风格不统一，出参方式对调用方最省心。
3.2 open 与工作表枚举：把 COM 生命周期管住
COM 对象必须成对释放，open里的每一步失败都要回滚，否则任务管理器里会堆一串不可见的 Excel 进程。这是我最开始翻车最多的地方。
// excelreader.cpp（节选） bool ExcelReader::open(const QString &filePath) { close(); // 先清掉上一次的状态 d->app = new QAxObject("Excel.Application", this); if (d->app->isNull()) { d->error = QStringLiteral("未检测到可用的 Excel 组件"); return false; } // 后台运行，不弹窗、不弹警告框 d->app->setProperty("Visible", false); d->app->setProperty("DisplayAlerts", false); d->workbooks = d->app->querySubObject("Workbooks"); d->workbook = d->workbooks->querySubObject( "Open(const QString&)", QDir::toNativeSeparators(filePath)); if (!d->workbook || d->workbook->isNull()) { close(); d->error = QStringLiteral("文件打开失败，检查路径或文件是否被占用"); return false; } d->sheetNames.clear(); QAxObject *sheets = d->workbook->querySubObject("Worksheets"); const int count = sheets->property("Count").toInt(); for (int i = 1; i <= count; ++i) { // COM 集合下标从 1 开始 QAxObject *sheet = sheets->querySubObject("Item(int)", i); d->sheetNames << sheet->property("Name").toString(); delete sheet; // 逐个释放查询出的子对象 } delete sheets; return true; }Visible=false与DisplayAlerts=false是必须的，前者防止界面闪出 Excel 窗口，后者防止文件格式提示框把程序卡死。QDir::toNativeSeparators把路径改成反斜杠，COM 的Open对正斜杠在部分版本上会报错，这个细节不值钱但很省事。
注意工作表集合的下标从 1 开始，写i=0会直接拿到空对象。循环里每次querySubObject产生的子对象要delete，qaxtypes的文档提过查询出的对象归调用方管理，不释放就是泄漏。
close()的实现顺序相反：先Close工作簿，再Quit应用，最后delete两个QAxObject。
void ExcelReader::close() { if (d->workbook) { d->workbook->dynamicCall("Close(Boolean)", false); // 不保存 delete d->workbook; d->workbook = nullptr; } if (d->app) { d->app->dynamicCall("Quit()"); delete d->app; d->app = nullptr; } d->workbooks = nullptr; d->sheetNames.clear(); }Close(false)的参数是“是否保存更改”，传false避免弹出保存确认。Quit之后必须delete，光调Quit不够，Qt 侧的包装对象不析构，进程可能还在。这个顺序如果写反——先删 app 再关 workbook——轻则内存报错，重则残留进程。
3.3 批量读取：一次 Value 拿整块区域
逐格取值在几十行的表上看不出问题，几百行乘十几列就会被用户感知到卡顿。我的做法是先拿UsedRange的行列数，再用一次Value把整块取回来。
QVector<QVector<QVariant>> ExcelReader::readSheet(const QString &sheetName, QString *error) { QVector<QVector<QVariant>> rows; if (!d->workbook) { if (error) *error = QStringLiteral("未打开文件"); return rows; } QAxObject *sheet = d->workbook->querySubObject("Worksheets(const QVariant&)", sheetName); if (!sheet || sheet->isNull()) { if (error) *error = QStringLiteral("工作表不存在：") + sheetName; return rows; } QAxObject *used = sheet->querySubObject("UsedRange"); QAxObject *rngRows = used->querySubObject("Rows"); QAxObject *rngCols = used->querySubObject("Columns"); const int rowCount = rngRows->property("Count").toInt(); const int colCount = rngCols->property("Count").toInt(); delete rngRows; delete rngCols; if (rowCount <= 0 || colCount <= 0) { delete used; delete sheet; return rows; } // 一次性取出整块区域的值，返回嵌套 QVariant QVariant value = used->dynamicCall("Value()"); delete used; delete sheet; const QVariantList rowList = value.toList(); rows.reserve(rowList.size()); for (const QVariant &rowVar : rowList) { const QVariantList cellList = rowVar.toList(); QVector<QVariant> row; row.reserve(cellList.size()); for (const QVariant &cell : cellList) row.push_back(cell); rows.push_back(row); } return rows; }UsedRange的范围从第一个非空单元格算起，不是从 A1 开始，这点在界面显示上会影响列对齐，后面避坑章节细说。dynamicCall("Value()")取回的是VariantList的嵌套结构，外层行、内层列，直接转成QVector就行。行列数先取是为了判断空表和预分配内存，reserve在几百行规模下能减少多次扩容。
Value返回的单元格可能是double、QString、bool或空QVariant。空单元格在部分版本里返回的是空变体而不是空串，界面显示时要统一转成toString()，否则会在表格里看到QVariant(Invalid)之类的东西。
4. 数据显示：QTableWidget 填充与列宽控制
4.1 刷表流程：先定行列再逐格写入
QTableWidget的行列必须先设好再填内容，填的过程中改尺寸会触发重排。表头我习惯直接用第一行数据填充，同时把列宽按内容自适应一次。
void MainWindow::showSheet(const QString &sheetName) { QString err; const auto data = m_reader->readSheet(sheetName, &err); if (data.isEmpty()) { statusBar()->showMessage(err); return; } QTableWidget *table = ui->tableWidget; table->setUpdatesEnabled(false); // 批量写入期间暂停重绘 table->clear(); table->setRowCount(data.size() - 1); // 首行当表头 table->setColumnCount(data.first().size()); table->setHorizontalHeaderLabels( [&]{ QStringList h; for (const QVariant &v : data.first()) h << v.toString().trimmed(); return h; }()); for (int r = 1; r < data.size(); ++r) { const auto &row = data.at(r); for (int c = 0; c < row.size() && c < table->columnCount(); ++c) { auto *item = new QTableWidgetItem(row.at(c).toString()); if (c == 0) item->setTextAlignment(Qt::AlignCenter); table->setItem(r - 1, c, item); } } table->resizeColumnsToContents(); table->setUpdatesEnabled(true); }setUpdatesEnabled(false)是最便宜的性能优化，几百行乘十几列的写入期间不重绘，写完整块刷新一次，肉眼可见地快。setRowCount(data.size() - 1)减一是因为首行被拿来当表头了，如果表格本身没有表头行，就把这段改成从 0 开始并手动设表头。
setItem会接管QTableWidgetItem的所有权，不需要自己 delete；但已经存在的旧 item 在clear()时才释放，所以刷表前必须clear()，否则会看到新旧数据叠在一起。
4.2 列宽与数据格式：别让数字变成科学计数法
resizeColumnsToContents好用但会算出极宽的列，遇到过一列备注写得特别长，整个表格被撑到视口外。我的折中做法是设置上限，超出部分交给用户拖动或双击自适应。
// 在 resizeColumnsToContents 之后调用 const int maxWidth = 320; for (int c = 0; c < table->columnCount(); ++c) { if (table->columnWidth(c) > maxWidth) table->setColumnWidth(c, maxWidth); table->horizontalHeaderItem(c)->setToolTip( table->horizontalHeaderItem(c)->text()); // 表头过长时可查看完整列名 }数字格式的问题更烦人。Value取回的整型可能变成20.000000，长数字串可能被转成科学计数法。稳妥做法是在转字符串前判断类型：QVariant::Double且整数值用QString::number(v.toDouble(), 'f', 0)，QVariant::Date或序列号区间用QDateTime转换。
static QString cellText(const QVariant &v) { if (!v.isValid() || v.isNull()) return QString(); switch (v.typeId()) { case QMetaType::Double: { const double dv = v.toDouble(); // Excel 日期序列号区间（约 1900-01-01 至 9999-12-31） if (dv > 1.0 && dv < 2958466.0 && !qFuzzyCompare(dv, qRound(dv))) return QDateTime::fromMSecsSinceEpoch( qRound64((dv - 25569.0) * 86400.0 * 1000.0)).toString("yyyy-MM-dd"); return QString::number(dv, 'f', (dv == qRound(dv)) ? 0 : 6).remove(QRegularExpression("0+$")).remove(QRegularExpression("\\.$")); } case QMetaType::Bool: return v.toBool() ? QStringLiteral("是") : QStringLiteral("否"); default: return v.toString(); } }25569 是 Unix 纪元与 Excel 纪元之间的天数差，这个换算对 1900 年之后的日期有效。末尾两个正则去掉多余的尾零，避免整列浮点数据带一长串 0。这段判断属于经验规则，如果业务里存在纯小数且恰好落在日期区间，最好换成按列读取NumberFormat判断，准确率更高但每列多一次 COM 调用。
提示：
resizeColumnsToContents在行数很多时开销不小，超过两三千行建议关掉自动列宽，改成固定宽度加ElideRight。
4.3 大表的分页与懒加载
表格行数上到万级，QTableWidget的 item 机制本身就会吃内存，一个 item 几十字节，十万格就是几十兆，加上刷新时卡顿明显。我的处理是读回来的二维数据整块留在内存，但界面只渲染当前页，翻页时重填。
void MainWindow::showPage(int page, int pageSize) { const int start = page * pageSize; const int end = qMin(start + pageSize, m_cache.size()); ui->tableWidget->setUpdatesEnabled(false); ui->tableWidget->clearContents(); ui->tableWidget->setRowCount(end - start); for (int r = start; r < end; ++r) for (int c = 0; c < m_cache.at(r).size(); ++c) ui->tableWidget->setItem(r - start, c, new QTableWidgetItem(cellText(m_cache.at(r).at(c)))); ui->tableWidget->setUpdatesEnabled(true); ui->pageLabel->setText(QString("%1 / %2").arg(page + 1) .arg(qCeil(double(m_cache.size()) / pageSize))); }m_cache是readSheet的返回值，分页参数pageSize我一般给 200，兼顾滚动流畅和一屏信息量。这一层是显示侧的优化，源头读 Excel 的时间没变；如果读表本身也慢，就该考虑在上层加个缓存文件，或者干脆切到不依赖 COM 的解析库。
5. 避坑排查：五条血泪记录照着对
5.1 现象：程序退出后任务管理器残留 EXCEL.EXE
原因基本是Quit没调，或者QAxObject包装对象没delete。COM 的引用计数在 Qt 侧由包装对象管理，只Quit不析构时，引用还在，进程就不退。解决是把释放顺序固定成：Workbook->Close(false)→delete workbook→Application->Quit()→delete app，并在open失败分支里也走同一个close()。我后来在open开头无条件先close()，就是为了防上一次的残留。
5.2 现象：querySubObject返回空对象，读到的行列数是 0
UsedRange拿的是“已使用区域”，如果整张表只有格式没有值，或者数据从 C5 才开始，行列数会偏小甚至为 0。解决是先判断rowCount <= 0直接返回空，不要往下走；需要严格按 A1 起算时，改用Range("A1:" + lastCell)显式指定范围，其中lastCell由UsedRange的Address解析出来。另外工作表名带空格或特殊字符时，Worksheets(const QVariant&)的参数用表名而不是索引更稳。
5.3 现象：单元格显示科学计数法或日期变成一串数字
前者是toString()对double的默认转换行为，后者是日期序列号没换算。解决就是 4.2 里那段cellText，按typeId分支处理。还有一种情况是单元格的值本身是文本格式的“'00123”，Value取回来就是字符串，前导零会保留，这反而是好事，别画蛇添足去转数字。
5.4 现象：文件被占用时打开卡死或直接崩
DisplayAlerts=false只挡提示框，文件被其他进程锁住时Open会阻塞一段时间再失败。解决是打开前用QFileInfo检查存在与可读，打开后用isNull()判断，失败时给明确文案；还可以在界面层的打开按钮上临时禁用，防止用户连点造成多个 COM 调用并发。批量导入时最好串行处理，每个文件读完立即close()。
5.5 现象：换台机器就报 “未检测到可用的 Excel 组件”
运行机器没装 Office，或者装的是精简版不带 Excel 组件，new QAxObject("Excel.Application")直接返回空对象。这不是代码问题，是部署环境问题。解决有两条：一是交付前确认目标机有完整 Office；二是封装层预留接口，在open返回失败时提示用户，同时后台支持切到第三方解析库。我曾经给一个现场环境排查了半天，最后发现是对方装的是 WPS 的旧版本，COM 接口兼容不全，换回标准 Office 就通了。
6. 进阶：把 reader 做成可替换的数据源
到这步 demo 能跑，但我更在意它能不能长期用。我的习惯是把ExcelReader抽成一个抽象的数据源接口，COM 实现和纯解析实现各自继承，界面层只依赖接口。这样现场没有 Office 的机器也能用，读大文件的性能也能换。
// tablereader.h：界面层只依赖这个接口 class TableReader { public: virtual ~TableReader() = default; virtual bool open(const QString &path, QString *error) = 0; virtual QStringList sheetNames() const = 0; virtual QVector<QVector<QVariant>> readSheet(const QString &name, QString *error) = 0; virtual void close() = 0; };选择实现类的判断不复杂：QAxObject存在且能创建成功，用 COM 实现；否则回落到纯解析实现。判断代码放在工厂函数里，界面构造时调一次就行，用户完全无感。
验证是否可靠，我一般看三个指标：一是读一个 500 行 × 12 列的表，耗时是否在一秒内；二是连续打开关闭 20 次，任务管理器里 Excel 进程数是否归零，这一条最能暴露生命周期问题；三是拿一张有合并单元格、日期列、空列的脏表跑一遍，看显示是否可读。合并单元格在 COM 下只有左上角有值，其余为空，界面上要不要向下填充取决于业务，我倾向不填，保持原样更诚实。
还有一个容易被忽略的点：QTableWidget的 item 数量超过一万之后，clear()和重建的开销会明显变大，我后来把刷表逻辑改成复用已有的 item，只setText，不 new。这个改动不复杂，但对频繁切换工作表的场景提升很直观。
从那次被残留进程搞到交付现场重启机器之后，我每次写 COM 相关代码都强制走一遍“开文件 → 读表 → 关文件 → 看进程”的闭环，再去接界面。这个习惯帮我省了不少后悔药。希望帮到你。
本文还有配套的精品资源，点击获取
