QXlsx 项目配置实战：在 Qt Creator 中集成 XLSX 读写库的完整指南（qmake 与 CMake 双方案）

• 数据分析

【免费下载链接】QXlsx

Excel file(*.xlsx) reader/writer library using Qt. Descendant of QtXlsxWriter.

项目地址： https://gitcode.com/gh_mirrors/qx/QXlsx

点击查看 免费下载

QXlsx 是一个基于 Qt 的 Excel（*.xlsx）读写库，本指南以仓库中的 HowToSetProject.ko.md（韩文）与 HowToSetProject.md（英文）为核心骨架，结合仓库内 HelloWorld 示例工程与 QXlsx.pri 源码，完整演示如何把 QXlsx 集成进你自己的 Qt 项目并成功编译运行。读完本文，你将掌握从克隆源码、创建 Qt 控制台项目、复制库代码、挂载 qmake 工程文件到编写第一段"写入并保存 xlsx"代码的全流程，同时了解等价的 CMake 集成方式，做到开箱即用、随手可跑。

一、QXlsx 项目速览：两种构建集成方式

QXlsx 是 QtXlsxWriter 的后继项目，用于在 Qt 程序中读取和写入 Excel 文件。仓库根目录下的 QXlsx 目录即库本体，其内部结构非常清晰：

• QXlsx/header：全部头文件，包括 xlsxdocument.h、xlsxcell.h、xlsxformat.h、xlsxworkbook.h 等公共 API 与私有实现头；
• QXlsx/source：全部实现源码（.cpp）；
• QXlsx/QXlsx.pri：qmake 专用导入文件（pri 即 "project include"，供 .pro 工程 include 使用）；
• QXlsx/CMakeLists.txt：CMake 专用构建脚本。

因此集成方式也分两条路：qmake 方式（文档主推、本文重点）与 CMake 方式（详见文末第八章）。文档明确指出，其讲解的步骤以 Windows + qmake 为例，Linux/macOS 下的做法与此类似。

二、第一步：克隆 QXlsx 源码

在命令行中执行 git clone 将 QXlsx 仓库克隆到本地工作目录：

git clone https://gitcode.com/gh_mirrors/qx/QXlsx.git

克隆完成后，目录中会出现仓库根下的 QXlsx/（库本体）、HelloWorld/（官方示例工程）等目录。文档中以 Windows 的 c:\workspace\github\QXlsx 作为源码所在路径，你可以替换为自己的实际目录。

三、第二步至第七步：在 Qt Creator 中创建你的应用项目

接下来的操作全部在 Qt Creator 中完成，对应原文档步骤 2~7：

1. 启动 Qt Creator（不熟悉 Qt Creator 基本操作的读者，可先参考 Qt 官方 IDE 文档）；
2. 通过菜单 File → New File or Project... 创建新项目；
3. 在项目类型向导中选择 Console Application（控制台应用程序）——原文档的示例即为控制台工程，无需 GUI 界面即可验证读写功能；
4. 为项目命名，原文档中的示例项目名称为 HelloQXlsx（下文代码与工程文件均以此为准）；
5. 确认项目创建完成，此时 Qt Creator 已生成工程目录与 HelloQXlsx.pro（qmake）工程文件。

提示：原文档中这一阶段的配图（markdown.data/03.jpg）展示了在 Qt Creator 菜单中选中 "New File or Project..." 的界面，如果你的 Qt Creator 版本界面布局不同，可对照功能入口操作。

四、第八步：把 QXlsx 库代码复制进你的项目

原文档推荐一种最直接、零配置的集成方式：把整个 QXlsx 库目录复制到你的应用项目目录下。在 Windows 上可以用资源管理器直接复制，也可以在命令行中使用 xcopy：

xcopy c:\workspace\github\QXlsx\QXlsx c:\workspace\HelloQXlsx /s /e

• /s：复制目录及其子目录（含空目录）；
• /e：复制空目录也一并复制（与 /s 连用）。

复制完成后，HelloQXlsx 项目目录下应同时出现 header/、source/ 与 QXlsx.pri，即库的完整可编译源码。

五、第九步：在 .pro 工程文件中挂载 QXlsx（qmake 核心配置）

这是整个 qmake 集成流程中最关键的一步。打开 Qt Creator 为你生成的 HelloQXlsx.pro，追加以下内容：

# QXlsx code for Application Qt project
QXLSX_PARENTPATH=./         # current QXlsx path is . (. means curret directory)
QXLSX_HEADERPATH=./header/  # current QXlsx header path is ./header/
QXLSX_SOURCEPATH=./source/  # current QXlsx source path is ./source/
include(./QXlsx.pri)

三行变量的含义（对应 QXlsx/QXlsx.pri 源码中的解析逻辑）：

变量	含义	本项目中的取值
QXLSX_PARENTPATH	QXlsx 库所在的父路径，用于定位头文件包含根	./（当前目录）
QXLSX_HEADERPATH	QXlsx 头文件目录	./header/
QXLSX_SOURCEPATH	QXlsx 源码目录	./source/

从 QXlsx.pri 源码可以看到，这三个变量并非必填：若未显式定义，会使用内置默认值（如 QXLSX_HEADERPATH = $$PWD/../QXlsx/header/），并在编译时打印提示信息；显式定义则打印实际生效的路径。这意味着即便你的项目目录结构与示例不同，也可以通过调整这三个变量自由定位库位置。

include(./QXlsx.pri) 会一次性完成以下事情：

• 追加 QT += core gui-private 等必需模块；
• 按 Qt 主版本自动设置 C++ 标准（Qt 5 用 C++11，Qt 6 用 C++17，见 QXlsx.pri 第 10~18 行）；
• 把 header/ 加入 INCLUDEPATH，并自动把所有头文件加入 HEADERS、所有源文件加入 SOURCES（第 58~149 行）；
• 按平台（win32-g++、win32-msvc2013/2015/2017/2019、unix、mac）追加对应的编译分支配置。

仓库中的官方示例 HelloWorld/HelloWorld.pro 就是这一做法的真实模板：它把 include(../QXlsx/QXlsx.pri) 指向上一级目录中的库，而将三个 QXLSX 路径变量以注释形式保留供按需取消注释：

TARGET = HelloWorld
TEMPLATE = app
QT += core
CONFIG += console
CONFIG -= app_bundle
DEFINES += QT_DEPRECATED_WARNINGS

# NOTE: You can fix value of QXlsx path of source code.
#  QXLSX_PARENTPATH=./
#  QXLSX_HEADERPATH=./header/
#  QXLSX_SOURCEPATH=./source/
include(../QXlsx/QXlsx.pri)

SOURCES += main.cpp

六、第十一步：编写入口代码 main.cpp

在 main.cpp 中包含 QXlsx 核心头文件、启用 QXlsx 命名空间，并编写一个写入示例。原文档给出的最小可运行代码（已补全注释）：

// main.cpp

#include <QCoreApplication>

#include "xlsxdocument.h"
#include "xlsxchartsheet.h"
#include "xlsxcellrange.h"
#include "xlsxchart.h"
#include "xlsxrichstring.h"
#include "xlsxworkbook.h"
using namespace QXlsx;

int main(int argc, char *argv[])
{
    QCoreApplication a(argc, argv);

    QXlsx::Document xlsx;
    xlsx.write("A1", "Hello Qt!"); // write "Hello Qt!" to cell(A,1). it's shared string.
    xlsx.saveAs("Test.xlsx"); // save the document as 'Test.xlsx'

    return 0;
    // return a.exec();
}

几点说明：

• 头文件与命名空间：文档示例显式 using namespace QXlsx;，仓库源码 TestExcel/main.cpp 中也能看到等价的 QXLSX_USE_NAMESPACE 宏用法，二者效果一致；
• xlsx.write("A1", "Hello Qt!")：向单元格 A1 写入字符串，字符串走 shared string（共享字符串表）机制；
• xlsx.saveAs("Test.xlsx")：将内存中的文档落盘保存为 Test.xlsx，成功时返回 true；
• 由于控制台示例无需进入事件循环，代码使用 return 0; 直接结束，事件循环调用 a.exec() 被注释掉。

进阶：读写一体的完整示例

原文档只演示了写入，仓库中的 HelloWorld/main.cpp 则进一步展示了"写入后再读回"的完整闭环，可作为验证库功能的标准模板：

#include "xlsxcellrange.h"
#include "xlsxchart.h"
#include "xlsxchartsheet.h"
#include "xlsxdocument.h"
#include "xlsxrichstring.h"
#include "xlsxworkbook.h"
using namespace QXlsx;

int main(int argc, char *argv[])
{
    QCoreApplication app(argc, argv);

    // [1] Writing excel file(*.xlsx)
    QXlsx::Document xlsxW;
    int row = 1;
    int col = 1;
    QVariant writeValue = QString("Hello Qt!");
    xlsxW.write(row, col, writeValue);
    if (xlsxW.saveAs("Test.xlsx")) {
        qDebug() << "[debug] success to write xlsx file";
    } else {
        qDebug() << "[debug][error] failed to write xlsx file";
        exit(-1);
    }

    // [2] Reading excel file(*.xlsx)
    Document xlsxR("Test.xlsx");
    if (xlsxR.load()) {
        Cell *cell = xlsxR.cellAt(row, col);
        if (cell != NULL) {
            QVariant var = cell->readValue();
            qDebug() << "[debug] cell(1,1) is " << var; // 'Hello Qt!'
        }
    }
    return 0;
}

其中 Document xlsxR("Test.xlsx") 以文件路径构造读取对象，load() 加载成功后可经 cellAt(row, col) 取单元格指针、readValue() 读取其值（数值、QDateTime、QString 等类型由 QVariant 统一承载）。

七、第十二步与第十三步：构建运行并验证产物

在 Qt Creator 中点击 Build and Run（构建并运行）即可。运行成功后，工作目录下会产生两类产物（对应原文档第十三步的验证环节）：

• HelloQXlsx.exe（Windows 下的可执行文件，其他平台为对应可执行文件）；
• Test.xlsx（由 saveAs 生成的 Excel 文件）。

用 Excel 或 LibreOffice 打开 Test.xlsx，即可看到 A1 单元格中的 "Hello Qt!" 字符串，说明 QXlsx 的写入链路（Document → 内存工作表 → 序列化 → 落盘）已完全打通。

八、补充方案：CMake 集成方式

若你的项目使用 CMake 而非 qmake，仓库提供了官方文档 HowToSetProject-cmake.md 与库级构建脚本 QXlsx/CMakeLists.txt。CMake 方式分为三种场景：

1）先安装、后查找（find_package）

mkdir build
cd build
cmake ../QXlsx/ -DCMAKE_INSTALL_PREFIX=... -DCMAKE_BUILD_TYPE=Release
cmake --build .
cmake --install .

然后在应用的 CMakeLists.txt 中：

find_package(QXlsxQt5 REQUIRED) # 或 QXlsxQt6
target_link_libraries(myapp PRIVATE QXlsx::QXlsx)

2）直接以子目录方式引用（add_subdirectory）

add_subdirectory(QXlsx)
target_link_libraries(myapp PRIVATE QXlsx::QXlsx)

3）通过 FetchContent 拉取源码

FetchContent_Declare(
  QXlsx
  GIT_REPOSITORY https://gitcode.com/gh_mirrors/qx/QXlsx.git
  GIT_TAG        sha-of-the-commit
  SOURCE_SUBDIR  QXlsx
)
FetchContent_MakeAvailable(QXlsx)
target_link_libraries(myapp PRIVATE QXlsx::QXlsx)

仓库中的官方 CMake 示例 HelloWorld/CMakeLists.txt 采用方案 2，并给出了完整的工程骨架（find_package(QT NAMES Qt6 Qt5 COMPONENTS Core Gui REQUIRED) + add_subdirectory(QXlsx) + target_link_libraries(HelloWorld PRIVATE QXlsx::QXlsx)），可直接对照参考。

从 QXlsx/CMakeLists.txt 源码可以看出 CMake 集成的几个关键点：

• 未显式设置 QT_VERSION_MAJOR 时，库会自行探测 Qt 6 / Qt 5（第 17~19 行），对应官方文档末尾的说明；
• 库按 Qt 主版本导出包名（QXlsxQt5 / QXlsxQt6），目标名统一为 QXlsx::QXlsx；
• BUILD_SHARED_LIBS 默认关闭，即默认以静态库方式链接（第 50 行），如需动态库可打开该选项。

九、常见问题与排查建议

结合 QXlsx.pri 源码与示例工程，给出以下排查要点：

• 路径配置错误导致头文件找不到：确认 QXLSX_PARENTPATH / QXLSX_HEADERPATH / QXLSX_SOURCEPATH 指向真实存在的目录，qmake 会在编译输出中打印三个变量最终生效的值，可据此核对；
• Qt 主版本与 C++ 标准：pri 文件会自动为 Qt 5 启用 C++11、为 Qt 6 启用 C++17，若使用较低版本编译器（如老旧的 MinGW）请确保编译器支持相应标准；
• 命名空间未引入：调用 Document、Cell 等类型前必须先 using namespace QXlsx; 或使用 QXLSX_USE_NAMESPACE 宏，否则会得到未声明标识符的编译错误；
• 读取失败：load() 返回 false 时，检查目标 .xlsx 文件是否存在、路径是否正确，以及文件是否被其他程序（如 Excel）占用；
• 跨平台差异：文档以 Windows 为讲解环境，Linux/macOS 下复制、.pro 配置与构建流程基本相同，仅路径分隔符与可执行文件后缀不同。

十、总结

以 HowToSetProject.ko.md 为核心的配置流程可概括为一条清晰主线：克隆 → 建项目 → 复制库 → 挂 pri → 写 main → 构建验证。qmake 方式胜在零外部依赖、纯文件拷贝即可编译；CMake 方式则与现代构建工具链、包管理流程更契合。无论选择哪条路径，只要按本文步骤操作并参照 HelloWorld 官方示例，即可在几分钟内让 QXlsx 在你的 Qt 工程中读写 Excel 文件。

赞 分享

• 数据分析

【免费下载链接】QXlsx

Excel file(*.xlsx) reader/writer library using Qt. Descendant of QtXlsxWriter.

项目地址： https://gitcode.com/gh_mirrors/qx/QXlsx

点击查看 免费下载

相关推荐

• Mumble 构建指南：在 IDE 中集成 CMake 项目（Visual Studio / Qt Creator / VS Code）

  Mumble 构建指南：在 IDE 中集成 CMake 项目（Visual Studio / Qt Creator / VS Code） 本文面向希望在 Vis

  音视频 即时通讯

• QXlsx完整使用指南：Qt项目的Excel解决方案

  QXlsx完整使用指南：Qt项目的Excel解决方案 🚀 项目亮点速览 QXlsx是一个专为Qt开发者设计的Excel文件处理库，无需依赖Office软件即可

  数据分析

• CMake与DirectX集成实战：Windows图形项目的完整编译配置指南

  CMake与DirectX集成实战：Windows图形项目的完整编译配置指南 在Windows平台上开发图形应用程序时，CMake与DirectX的集成配置是每

  构建工具 开发工具 CLI

上一篇： ExplorerPatcher 完整指南：Windows 11 一键恢复 Windows 10 界面

下一篇： Ariakit 实战：用 textarea 渲染 Combobox，构建多行文本框内联自动补全（@ 用户 / Issue / : Emoji）