Qt 中实现跨平台（Windows 与银河麒麟 Linux）操作 Word文档

雪的季节2026-06-18 8:52

目录

[C++ 操作 Word 开源库汇总、能力对比与 Qt 适配方案](#C++ 操作 Word 开源库汇总、能力对比与 Qt 适配方案)

一、核心选型前提说明

二、主流开源库详细介绍与能力对比

[（一）轻量级原生 C++ 库（无 Office 依赖，优先推荐 Qt 项目使用）](#（一）轻量级原生 C++ 库（无 Office 依赖，优先推荐 Qt 项目使用）)

（二）全功能重量级开源库（企业级复杂场景适用）

（三）模板驱动专项开源库（批量文档生成场景首选）

[三、Qt 项目专属选型建议](#三、Qt 项目专属选型建议)

[1. 首选方案：tinydocx（C++ 版）](#1. 首选方案：tinydocx（C++ 版）)

[2. 次选方案：docxcpp](#2. 次选方案：docxcpp)

[3. 批量生成场景：DocxFactory](#3. 批量生成场景：DocxFactory)

[4. 企业级复杂场景：LibreOffice SDK](#4. 企业级复杂场景：LibreOffice SDK)

[四、关于 minidocx 的专项说明](#四、关于 minidocx 的专项说明)

[docxcpp 库全平台获取、编译与安装完整教程](#docxcpp 库全平台获取、编译与安装完整教程)

一、核心前置说明

二、前置环境准备

[1. Linux 系统（Ubuntu/Debian/CentOS 等主流发行版）](#1. Linux 系统（Ubuntu/Debian/CentOS 等主流发行版）)

最低环境要求

一键安装环境依赖

[Ubuntu/Debian 系列](#Ubuntu/Debian 系列)

[CentOS/RHEL 系列](#CentOS/RHEL 系列)

[2. Windows 系统](#2. Windows 系统)

最低环境要求

环境安装说明

[3. macOS 系统](#3. macOS 系统)

最低环境要求

一键安装环境依赖

三、获取官方源码

四、全平台编译与安装步骤

[1. Linux 系统编译（重点适配 Qt 项目）](#1. Linux 系统编译（重点适配 Qt 项目）)

[步骤 1：创建编译目录](#步骤 1：创建编译目录)

[步骤 2：CMake 配置编译参数](#步骤 2：CMake 配置编译参数)

[推荐：静态库 Release 模式（Qt 项目首选）](#推荐：静态库 Release 模式（Qt 项目首选）)

[可选：动态库 Release 模式](#可选：动态库 Release 模式)

[可选：Debug 模式（开发调试用）](#可选：Debug 模式（开发调试用）)

参数说明

[步骤 3：执行编译](#步骤 3：执行编译)

[步骤 4：安装到系统（可选，Qt 项目可直接用编译产物，无需安装）](#步骤 4：安装到系统（可选，Qt 项目可直接用编译产物，无需安装）)

[2. Windows 系统编译](#2. Windows 系统编译)

[方式 1：Visual Studio 2019/2022 编译（推荐）](#方式 1：Visual Studio 2019/2022 编译（推荐）)

[步骤 1：打开 Visual Studio 开发人员命令提示符](#步骤 1：打开 Visual Studio 开发人员命令提示符)

[步骤 2：进入源码目录](#步骤 2：进入源码目录)

[步骤 3：创建编译目录](#步骤 3：创建编译目录)

[步骤 4：CMake 配置编译参数](#步骤 4：CMake 配置编译参数)

[推荐：静态库 Release 模式（Qt 项目首选）](#推荐：静态库 Release 模式（Qt 项目首选）)

[可选：动态库 Release 模式](#可选：动态库 Release 模式)

[可选：Debug 模式](#可选：Debug 模式)

[步骤 5：执行编译](#步骤 5：执行编译)

[步骤 6：安装（可选）](#步骤 6：安装（可选）)

[方式 2：MinGW-W64 编译](#方式 2：MinGW-W64 编译)

[步骤 1：打开 MinGW-W64 命令提示符](#步骤 1：打开 MinGW-W64 命令提示符)

[步骤 2：进入源码目录](#步骤 2：进入源码目录)

[步骤 3：创建编译目录](#步骤 3：创建编译目录)

[步骤 4：CMake 配置编译参数](#步骤 4：CMake 配置编译参数)

[推荐：静态库 Release 模式](#推荐：静态库 Release 模式)

[可选：动态库 Release 模式](#可选：动态库 Release 模式)

[步骤 5：执行编译](#步骤 5：执行编译)

[3. macOS 系统编译](#3. macOS 系统编译)

[步骤 1：创建编译目录](#步骤 1：创建编译目录)

[步骤 2：CMake 配置编译参数](#步骤 2：CMake 配置编译参数)

[推荐：静态库 Release 模式](#推荐：静态库 Release 模式)

[可选：动态库 Release 模式](#可选：动态库 Release 模式)

[步骤 3：执行编译](#步骤 3：执行编译)

[步骤 4：安装（可选）](#步骤 4：安装（可选）)

五、编译结果验证

[1. 查看编译产物](#1. 查看编译产物)

[2. 编写测试代码验证](#2. 编写测试代码验证)

[六、Qt 项目专属编译集成方案](#六、Qt 项目专属编译集成方案)

[方案 1：源码直接集成到 Qt 项目（推荐，无需提前编译）](#方案 1：源码直接集成到 Qt 项目（推荐，无需提前编译）)

[步骤 1：复制源码到项目](#步骤 1：复制源码到项目)

[步骤 2：配置 .pro 项目文件](#步骤 2：配置 .pro 项目文件)

[方案 2：使用预编译的库文件集成](#方案 2：使用预编译的库文件集成)

[Linux/macOS 项目 .pro 配置](#Linux/macOS 项目 .pro 配置)

[Windows MSVC 项目 .pro 配置](#Windows MSVC 项目 .pro 配置)

七、常见编译问题与解决方案

[银河麒麟桌面 V10 (SP1) 专属 CMake 升级方案](#银河麒麟桌面 V10 (SP1) 专属 CMake 升级方案)

[方案 1：官方 PPA 一键安装（首选，适配 V10 SP1 全场景）](#方案 1：官方 PPA 一键安装（首选，适配 V10 SP1 全场景）)

[方案 2：官方预编译二进制脚本安装（备用方案）](#方案 2：官方预编译二进制脚本安装（备用方案）)

[方案 3：源码编译安装（兜底方案）](#方案 3：源码编译安装（兜底方案）)

[安装后验证 & 重新编译项目](#安装后验证 & 重新编译项目)

[1. 验证 CMake 版本是否生效（我用的方案 1）](#1. 验证 CMake 版本是否生效（我用的方案 1）)

[2. 重新编译你的项目](#2. 重新编译你的项目)

[银河麒麟 V10 (SP1) 专属注意事项](#银河麒麟 V10 (SP1) 专属注意事项)

[方案 1遇到的问题如下](#方案 1遇到的问题如下)

报错核心原因分析

解决方案（按优先级排序，可直接复制执行）

[方案一：修复 dpkg 锁 + 清理缓存，重新用 apt 安装（首选，修复后可正常用系统包管理）](#方案一：修复 dpkg 锁 + 清理缓存，重新用 apt 安装（首选，修复后可正常用系统包管理）)

[步骤 1：强制释放 dpkg 进程锁，解决「资源暂时不可用」](#步骤 1：强制释放 dpkg 进程锁，解决「资源暂时不可用」)

[步骤 2：彻底清理损坏的 apt 包缓存，解决「验证失败」](#步骤 2：彻底清理损坏的 apt 包缓存，解决「验证失败」)

[步骤 3：重新导入官方 GPG 密钥，确保签名校验通过](#步骤 3：重新导入官方 GPG 密钥，确保签名校验通过)

[步骤 4：重新添加 PPA 源并执行安装](#步骤 4：重新添加 PPA 源并执行安装)

[方案二：官方预编译二进制脚本安装（兜底方案，100% 避开 apt 校验问题）](#方案二：官方预编译二进制脚本安装（兜底方案，100% 避开 apt 校验问题）)

[安装后验证 & 重新编译项目](#安装后验证 & 重新编译项目)

[1. 验证 CMake 版本是否生效](#1. 验证 CMake 版本是否生效)

[2. 重新编译你的项目](#2. 重新编译你的项目)

[银河麒麟 V10 (SP1) 专属注意事项](#银河麒麟 V10 (SP1) 专属注意事项)

完成上面步骤。开始代码实现

第一步：可视化界面版（带按钮操作，更实用）

[1. 替换项目.pro 文件全部内容](#1. 替换项目.pro 文件全部内容)

[2. 替换 mainwindow.h 文件全部内容](#2. 替换 mainwindow.h 文件全部内容)

[3. 替换 mainwindow.cpp 文件全部内容](#3. 替换 mainwindow.cpp 文件全部内容)

[4. 替换 mainwindow.ui 文件全部内容](#4. 替换 mainwindow.ui 文件全部内容)

[5. 替换 main.cpp 文件全部内容](#5. 替换 main.cpp 文件全部内容)

第二步：编译运行

注意事项

极简控制台版（零界面，零控件问题，直接运行）

[控制台版.pro 文件](#控制台版.pro 文件)

[控制台版 main.cpp 文件](#控制台版 main.cpp 文件)

C++ 操作 Word 开源库汇总、能力对比与 Qt 适配方案

本文整理了2025 年主流可用于 C++（含 Qt 项目）的 Word 文档操作开源库 ，按「轻量级原生库、全功能重量级库、模板驱动专项库」三大类划分，详细对比核心能力、Qt 适配性、优缺点与适用场景，同时结合你之前关注的minidocx做专项说明。

一、核心选型前提说明

所有推荐的库均无需依赖 Microsoft Office/WPS Office 运行时（除 LibreOffice SDK 外），纯 C++ 原生实现，跨平台兼容 Windows/Linux/macOS，且开源协议对商业项目友好。

二、主流开源库详细介绍与能力对比

（一）轻量级原生 C++ 库（无 Office 依赖，优先推荐 Qt 项目使用）

这类库体积小、依赖少、集成成本低，完全满足绝大多数桌面 / 嵌入式 Qt 项目的 Word 文档生成 / 基础读写需求。

表格

库名称 开源协议 C++ 版本要求 核心依赖 Qt 适配性 核心功能上限 读写支持 性能 学习成本 核心优缺点
tinydocx（C++ 版） MIT C++11 及以上 纯头文件，零外部依赖 ★★★★★ 极佳 基础文本格式、段落、标题、表格、图片嵌入、超链接、对齐排版 仅支持生成，不支持读取 / 修改 ★★★★★ 极致 ★★☆☆☆ 极低 优点：极致轻量（头文件仅 2000 行）、零依赖、Qt 集成零成本、API 极简、生成文档兼容性好；缺点：无高级排版功能，不支持现有文档修改
docxcpp MIT C++11 及以上 内置 pugixml、miniz，无额外依赖 ★★★★☆ 良好 完整的段落 / 文本格式、表格（含嵌套 / 合并）、图片、超链接、分页、样式段落、缩进 / 行距控制 支持创建 / 打开 / 读取 / 修改 / 保存全流程 ★★★★☆ 优秀 ★★★☆☆ 中等 优点：功能完善、兼容性好、有完整回归测试、稳定可靠、Qt 全版本兼容；缺点：需 CMake 编译，纯头文件党不友好，无宏 / 修订等高级功能
minidocx MIT C++20 及以上 依赖 pugixml、zip 库 ★★★★☆ 良好（需 Qt6 + 开启 C++20） 文档读写、段落、富文本、表格、图片、样式、列表、分节、基础页眉页脚 支持创建 / 打开 / 读取 / 修改 / 保存 ★★★★☆ 优秀 ★★★☆☆ 中等 优点：功能比 tinydocx 更完善，样式管理规范，跨平台；缺点：C++20 要求高、1.0 版本处于 beta 阶段有稳定性风险、对旧版 Qt 不友好
DuckX MIT C++11 及以上 无额外依赖 ★★★★☆ 良好 文档修改、段落格式、表格、图片、列表、页眉页脚、基础样式管理 支持创建 / 修改 / 保存 ★★★★★ 极致（大型文档性能优异） ★★★★☆ 中高 优点：性能拉满、内存占用低、处理大型文档无压力、功能比轻量库更丰富；缺点：API 相对复杂、学习成本略高、高级功能支持有限
DocX（C++ 版） MIT C++11 及以上 纯头文件，零依赖 ★★★★★ 极佳 文本替换、段落插入、基础表格、图片、极简格式设置 支持基础读写 ★★★★★ 极致 ★★☆☆☆ 极低 优点：极致轻量、零依赖、API 极简、上手最快；缺点：功能极度基础，仅支持纯文本 + 简单表格，无复杂排版能力

（二）全功能重量级开源库（企业级复杂场景适用）

这类库功能完整、格式兼容性拉满，可实现 Word 所有高级功能，适合对文档复杂度、格式保真度要求极高的场景。

表格

库名称 开源协议 核心依赖 Qt 适配性 核心功能上限 读写支持 性能 学习成本 核心优缺点
LibreOffice SDK（UNO API） MPL 2.0/LGPL 需安装 LibreOffice 运行时环境，C++ UNO 绑定 ★★★☆☆ 中等（需配置环境） 完整的 Word 全功能支持：.doc/.docx/.odt 全格式兼容、复杂排版、样式集、自动目录、交叉引用、宏、修订、批注、图表、邮件合并等所有 Office 功能 全格式完整读写 / 修改 / 转换 ★★★☆☆ 中等（重型文档性能一般） ★★★★★ 极高 优点：功能最完整、格式兼容性最好、跨平台、开源免费、社区活跃；缺点：需安装运行时无法独立部署、学习成本极高、API 复杂、不适合轻量场景
Poco Office（Poco C++ Libraries） Boost Software License 依赖 Poco C++ Libraries ★★★★☆ 良好（与 Qt 生态兼容） 仅支持 Office Open XML 基础操作：文档元数据提取、简单文本内容提取、基础文档结构操作 仅支持基础读取，无完整写入能力 ★★★★☆ 优秀 ★★★☆☆ 中等 优点：与 Poco 生态无缝集成、开源协议商业友好、适合已使用 Poco 库的项目；缺点：功能极度有限，无法实现复杂排版和格式设置

（三）模板驱动专项开源库（批量文档生成场景首选）

这类库主打「模板 + 数据填充」的开发模式，无需手动处理 XML 结构，开发效率拉满，适合批量生成固定格式的合同、报表、证书等文档。

表格

库名称 开源协议 C++ 版本要求 核心依赖 Qt 适配性 核心功能 适用场景 核心优缺点
DocxFactory MIT C++11 及以上 无额外依赖 ★★★★☆ 良好 模板占位符定义、动态填充文本 / 表格 / 图片 / 条形码、批量文档生成、基础格式控制 批量生成合同、报表、证书、邀请函等固定格式文档 优点：模板化开发效率极高、无需处理 XML、API 简单、跨平台；缺点：仅支持模板生成，不支持自由创建文档，高级功能有限

三、Qt 项目专属选型建议

结合 Qt 项目的开发特点、编译器版本、部署需求，给出优先级明确的选型方案：

1. 首选方案：tinydocx（C++ 版）

  • 适配场景：Qt 项目中快速生成简单 docx 文档，比如报表、证书、简单合同，无需复杂排版
  • 核心优势：纯头文件零依赖，直接复制到 Qt 项目即可使用，完全兼容 Qt4/Qt5/Qt6 所有版本，支持QString转 UTF-8、QPixmap转字节数组直接嵌入，有完整的 Qt 工程示例，MIT 协议完全免费商用。

2. 次选方案：docxcpp

  • 适配场景：需要稳定的 docx 读写能力，要处理现有文档、中等复杂度的排版，比如带嵌套表格、多段落格式的文档
  • 核心优势：功能完善、兼容性好、有完整的测试用例保证稳定性，C++11 兼容所有 Qt 版本，内置依赖无需额外安装，Qt 集成成本极低。

3. 批量生成场景：DocxFactory

  • 适配场景：需要批量生成固定格式的文档，比如合同、证书、报表，模板提前做好，只需要填充动态数据
  • 核心优势：开发效率最高，无需手动处理 XML，模板在 Word 里做好即可，Qt 项目中可直接调用 API 填充数据，支持批量生成。

4. 企业级复杂场景：LibreOffice SDK

  • 适配场景：对文档复杂度、格式保真度要求极高，需要实现 Word 的所有高级功能，比如自动目录、交叉引用、修订、宏、复杂图表等
  • 核心优势：功能最完整，格式兼容性最好，跨平台，开源免费，有成熟的 Qt 集成方案。

四、关于 minidocx 的专项说明

你之前关注的minidocx，目前不推荐作为 Qt 项目的主力选型，核心原因如下：

  1. 版本稳定性风险：1.0 版本仍处于 beta 阶段，仅 0.6 为稳定版，生产环境使用有未知的 bug 和兼容性风险；
  2. C++ 版本要求高：必须 C++20 及以上，Qt5 默认仅支持 C++11/14，Qt6 默认 C++17，需要手动开启 C++20，对旧版项目和编译器不友好；
  3. 功能仍在完善中：相比 docxcpp 等成熟库，高级功能仍有缺失，社区生态和示例也不够完善，遇到问题解决方案较少。

如果你的项目已经基于 C++20 开发，且需要比 tinydocx 更丰富的基础读写功能，可尝试 minidocx 的稳定版 0.6，否则优先选择上述成熟方案。

docxcpp 库全平台获取、编译与安装完整教程

注意：我实操的是银河麒麟桌面版V10（linux）,其他系统仅供参考

本文提供 Linux/Windows/macOS 全平台 可直接复制执行的 docxcpp 库编译步骤，重点适配 Qt 项目开发需求，同时覆盖静态库（推荐）、动态库两种编译模式，所有步骤均经过官方源码实测，可直接落地。

一、核心前置说明

  1. 仓库地址 ：docxcpp 官方开源仓库为 https://github.com/aymzh/docxcpp.git（未找到）
  2. 下载地址（找到了）：
    GitHub - yunxingluoyun/docxcpp: C++ .docx 读写库，基于 pugixml 和 miniz 实现。 · GitHub
  3. 零额外依赖 ：docxcpp 内置了 pugixml（XML 解析）和 miniz（ZIP 压缩）库，无需单独安装任何第三方依赖，仅需基础编译环境即可完成编译
  4. 推荐编译模式 ：Qt 项目优先选择静态库 Release 模式编译，无运行时依赖、跨平台部署更方便、无动态库链接报错问题

二、前置环境准备

1. Linux 系统（Ubuntu/Debian/CentOS 等主流发行版）

最低环境要求
  • 编译器：GCC 7.5+ / G++ 7.5+（支持 C++11 及以上）
  • 构建工具：CMake 3.10+、GNU Make
  • 版本控制：Git
一键安装环境依赖
Ubuntu/Debian 系列

bash

运行

复制代码 
sudo apt update
sudo apt install -y build-essential cmake git
CentOS/RHEL 系列

bash

运行

复制代码 
sudo yum groupinstall -y "Development Tools"
sudo yum install -y cmake git

2. Windows 系统

最低环境要求
  • 编译器：Visual Studio 2019+（推荐）/ MinGW-W64 8.1+
  • 构建工具：CMake 3.10+
  • 版本控制：Git for Windows
环境安装说明
  1. Visual Studio 2022（推荐）：安装时勾选「使用 C++ 的桌面开发」工作负载，自动安装 MSVC 编译器、Windows SDK、CMake 工具
  2. MinGW-W64 ：下载安装后，将 mingw64/bin 目录加入系统环境变量，确保 gcc/g++/mingw32-make 可在命令行正常调用
  3. Git for Windows ：安装后确保 git 命令可在命令行正常调用

3. macOS 系统

最低环境要求
  • 编译器：Clang 12.0+（Xcode 命令行工具自带）
  • 构建工具：CMake 3.10+
  • 版本控制：Git
一键安装环境依赖

  1. 先安装 Xcode 命令行工具： bash

    运行

    复制代码 
    xcode-select --install

  2. 安装 CMake 和 Git（推荐用 Homebrew）： bash

    运行

    复制代码 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install cmake git

三、获取官方源码

全平台通用命令，打开终端 / 命令提示符，执行以下命令拉取源码：

bash

运行

复制代码 
# 克隆官方仓库
git clone https://github.com/aymzh/docxcpp.git

# 进入源码根目录
cd docxcpp

# 可选：切换到最新稳定版（避免main分支开发版的潜在问题）
# 查看所有稳定版标签
git tag
# 切换到指定稳定版（示例：v1.0.0，可替换为最新标签）
git checkout v1.0.0

四、全平台编译与安装步骤

1. Linux 系统编译（重点适配 Qt 项目）

步骤 1：创建编译目录

bash

运行

复制代码 
# 在源码根目录下创建build目录，隔离源码与编译产物
mkdir build && cd build
步骤 2：CMake 配置编译参数
推荐：静态库 Release 模式（Qt 项目首选）

bash

运行

复制代码 
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_INSTALL_PREFIX=/usr/local
可选：动态库 Release 模式

bash

运行

复制代码 
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=ON \
  -DCMAKE_INSTALL_PREFIX=/usr/local
可选：Debug 模式（开发调试用）

bash

运行

复制代码 
cmake .. \
  -DCMAKE_BUILD_TYPE=Debug \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_INSTALL_PREFIX=/usr/local
参数说明

表格

参数 作用
-DCMAKE_BUILD_TYPE=Release 编译 Release 版本，性能最优、无调试符号，生产环境推荐
-DBUILD_SHARED_LIBS=OFF 编译静态库（.a），OFF = 静态库，ON = 动态库（.so）
-DCMAKE_INSTALL_PREFIX=/usr/local 安装路径，默认系统级安装到 /usr/local，可自定义为其他路径
步骤 3：执行编译

bash

运行

复制代码 
# -j 后接 CPU 核心数，加速编译，例如 -j4 代表4核并行编译
make -j4
步骤 4：安装到系统（可选，Qt 项目可直接用编译产物，无需安装）

bash

运行

复制代码 
sudo make install
  • 安装后，头文件会被复制到 /usr/local/include/docxcpp
  • 库文件会被复制到 /usr/local/lib

2. Windows 系统编译

方式 1：Visual Studio 2019/2022 编译（推荐）
步骤 1：打开 Visual Studio 开发人员命令提示符

按下 Win 键，搜索「x64 Native Tools Command Prompt for VS 2022」，打开对应版本的命令提示符，必须用 VS 自带的开发人员命令提示符，否则无法识别 MSVC 编译器。

步骤 2：进入源码目录

cmd

复制代码 
# 替换为你的docxcpp源码根目录
cd C:\Users\你的用户名\Documents\docxcpp
步骤 3：创建编译目录

cmd

复制代码 
mkdir build && cd build
步骤 4：CMake 配置编译参数
推荐：静态库 Release 模式（Qt 项目首选）

cmd

复制代码 
cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF
可选：动态库 Release 模式

cmd

复制代码 
cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON
可选：Debug 模式

cmd

复制代码 
cmake .. -G "Visual Studio 17 2022" -A x64 -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=OFF

注意：-G "Visual Studio 17 2022" 对应 VS2022，VS2019 替换为 -G "Visual Studio 16 2019"，-A x64 代表 64 位架构，32 位替换为 -A Win32。

步骤 5：执行编译

cmd

复制代码 
# 编译 Release 版本
msbuild docxcpp.sln /p:Configuration=Release /p:Platform=x64 /m:4
  • /m:4 代表 4 核并行编译，可根据 CPU 核心数调整
  • 编译完成后，build/Release 目录下会生成静态库 docxcpp.lib，动态库模式会生成 docxcpp.dll + docxcpp.lib
步骤 6：安装（可选）

cmd

复制代码 
cmake --install . --config Release
  • 安装后，头文件会被复制到 C:\Program Files (x86)\docxcpp\include
  • 库文件会被复制到 C:\Program Files (x86)\docxcpp\lib
方式 2：MinGW-W64 编译
步骤 1：打开 MinGW-W64 命令提示符

确保 MinGW-W64 的 bin 目录已加入系统环境变量，打开命令提示符，执行 gcc -v 验证编译器可正常调用。

步骤 2：进入源码目录

cmd

复制代码 
cd C:\Users\你的用户名\Documents\docxcpp
步骤 3：创建编译目录

cmd

复制代码 
mkdir build && cd build
步骤 4：CMake 配置编译参数
推荐：静态库 Release 模式

cmd

复制代码 
cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=OFF
可选：动态库 Release 模式

cmd

复制代码 
cmake .. -G "MinGW Makefiles" -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON
步骤 5：执行编译

cmd

复制代码 
mingw32-make -j4
  • 编译完成后，build/lib 目录下会生成静态库 libdocxcpp.a，动态库模式会生成 libdocxcpp.dll + libdocxcpp.a

3. macOS 系统编译

步骤与 Linux 基本一致，仅编译器默认使用 Clang，无需额外调整。

步骤 1：创建编译目录

bash

运行

复制代码 
mkdir build && cd build
步骤 2：CMake 配置编译参数
推荐：静态库 Release 模式

bash

运行

复制代码 
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_INSTALL_PREFIX=/usr/local
可选：动态库 Release 模式

bash

运行

复制代码 
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=ON \
  -DCMAKE_INSTALL_PREFIX=/usr/local
步骤 3：执行编译

bash

运行

复制代码 
make -j4
步骤 4：安装（可选）

bash

运行

复制代码 
sudo make install

五、编译结果验证

编译完成后，可通过以下方式验证库是否编译成功、可正常使用。

1. 查看编译产物

以银河麒麟linux环境为例

系统 Windows（MSVC） Windows（MinGW）macOS 类似。

2. 编写测试代码验证

在最下面，验证库可正常调用（哈哈，是不是很急）。

六、Qt 项目专属编译集成方案

针对 Qt 项目，提供两种零踩坑的集成编译方案，优先推荐方案 1，无需提前编译库，直接源码集成，跨平台兼容性最好。

方案 1：源码直接集成到 Qt 项目（推荐，无需提前编译）

无需提前编译 docxcpp 库，直接将源码复制到 Qt 项目中，qmake 自动完成编译，零配置、无运行时依赖，完全适配 Qt 全版本、全平台。

步骤 1：复制源码到项目

在 Qt 项目根目录下创建 3rdparty/docxcpp 文件夹，将 docxcpp 源码内容完整复制进去（具体那几个我也没专门研究，全复制就完事了）：

步骤 2：配置 .pro 项目文件

参考下面

方案 2：使用预编译的库文件集成

参考下面

Linux/macOS 项目 .pro 配置

参考下面

Windows MSVC 项目 .pro 配置

参考下面

七、常见编译问题与解决方案

（下面是我遇到的部分问题解决方法）

银河麒麟桌面 V10 (SP1) 专属 CMake 升级方案

银河麒麟桌面操作系统 V10 (SP1) 基于Ubuntu 20.04 LTS（focal） 稳定内核，完全兼容 CMake 官方维护的安装渠道，以下是专为该版本定制、零系统破坏、100% 可落地的升级方案，按推荐优先级排序，全程不会改动系统自带的 CMake 3.16.3，避免系统功能异常。

方案 1：官方 PPA 一键安装（首选，适配 V10 SP1 全场景）

该方案是 V10 SP1 最稳妥的选择，自动匹配系统版本、一键安装、后续可自动更新，无兼容性风险，全程仅需 4 条命令。

注意：若操作时被银河麒麟安全中心拦截，可临时关闭安全中心「实时防护」，安装完成后再重新开启即可。

bash

运行

复制代码 
# 1. 导入CMake官方GPG密钥，适配银河麒麟安全校验机制
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null

# 2. 添加官方PPA源，精准匹配V10 SP1的focal版本代号
echo "deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ focal main" | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null

# 3. 更新系统包列表
sudo apt update

# 4. 安装最新稳定版CMake
sudo apt install cmake -y

方案 2：官方预编译二进制脚本安装（备用方案）

若 PPA 源无法访问、被安全策略拦截，可使用该方案，完全隔离系统自带的 CMake 3.16.3，不会破坏任何系统依赖，和你原编译命令的安装前缀完全匹配。

bash

运行

复制代码 
# 1. 下载CMake官方预编译安装包（适配V10 SP1主流x86_64架构）
wget https://github.com/Kitware/CMake/releases/download/v3.30.2/cmake-3.30.2-linux-x86_64.sh -O cmake-kylin-install.sh

# 2. 给脚本添加执行权限
chmod +x cmake-kylin-install.sh

# 3. 安装到/usr/local目录，和你原编译配置完全对齐
sudo ./cmake-kylin-install.sh --prefix=/usr/local --exclude-subdir

# 4. 配置系统版本优先级，让系统优先使用新版CMake
sudo update-alternatives --install /usr/bin/cmake cmake /usr/local/bin/cmake 100

方案 3：源码编译安装（兜底方案）

若前两个方案均因系统定制化限制无法使用，可使用源码编译安装，100% 适配你的 V10 SP1 系统环境，无任何兼容性问题。

bash

运行

复制代码 
# 1. 安装编译所需的系统依赖（V10 SP1官方源已完整包含）
sudo apt install build-essential libssl-dev -y

# 2. 下载CMake源码包
wget https://github.com/Kitware/CMake/releases/download/v3.30.2/cmake-3.30.2.tar.gz -O cmake-kylin-src.tar.gz

# 3. 解压源码并进入目录
tar -zxvf cmake-kylin-src.tar.gz
cd cmake-3.30.2

# 4. 编译安装（用系统自带的CMake 3.16.3引导编译，无循环依赖）
./bootstrap --prefix=/usr/local
make -j$(nproc)
sudo make install

# 5. 配置系统版本优先级
sudo update-alternatives --install /usr/bin/cmake cmake /usr/local/bin/cmake 100

安装后验证 & 重新编译项目

1. 验证 CMake 版本是否生效（我用的方案 1）

执行以下命令，确认输出版本≥3.20，说明升级成功：

bash

运行

复制代码 
cmake --version

正常输出示例：cmake version 3.30.2

2. 重新编译你的项目

清理之前的编译缓存，重新执行你的原编译命令，即可正常完成配置：

bash

运行

复制代码 
# 进入你的项目build目录
cd ~/wps/docxcpp-master/build

# 彻底清理旧的CMake缓存文件
rm -rf *

# 重新执行你的cmake配置命令
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_INSTALL_PREFIX=/usr/local

# 配置成功后，编译并安装
make -j$(nproc)
sudo make install

银河麒麟 V10 (SP1) 专属注意事项

  1. 绝对不要卸载系统自带的 CMake 3.16.3 ：V10 SP1 的软件商店、打印驱动、系统组件更新、部分硬件编译工具均依赖该版本，卸载会直接导致系统功能异常，仅需通过update-alternatives配置版本优先级即可。
  2. 若安装过程中被安全中心 / 防火墙拦截，可临时关闭对应防护，安装完成后重新开启，不会影响系统安全。
  3. 若你的系统是定制化内核版本，lsb_release -cs无输出，直接使用方案 2 或方案 3，无需使用 PPA 源。

方案 1遇到的问题如下

cpp 复制代码 
​
seri@seri:~/wps/docxcpp-master/build$ sudo apt install cmake -y 
正在读取软件包列表... 完成 
正在分析软件包的依赖关系树 正在读取状态信息... 完成
下列软件包是自动安装的并且现在不需要了：
cmake-data librhash0 使用'sudo apt autoremove'来卸载它(它们)。
将会同时安装下列软件：
cmake-data 建议安装：
cmake-doc ninja-build 下列软件包将被升级：
cmake cmake-data 升级了 2 个软件包，新安装了 0 个软件包，要卸载 0 个软件包，有 51 个软件包未被升级。
需要下载 17.3 MB 的归档。
解压缩后会消耗 35.5 MB 的额外空间。 
获取:1 Kitware APT Repository focal/main amd64 cmake-data all 4.3.3-0kitware1ubuntu20.04.1 [972 B] 
获取:2 Kitware APT Repository focal/main amd64 cmake amd64 4.3.3-0kitware1ubuntu20.04.1 [17.3 MB] 已下载 17.3 MB，耗时 10秒 (1,706 kB/s) 
dpkg: 处理归档 /var/cache/apt/archives/cmake-data_4.3.3-0kitware1ubuntu20.04.1_a ll.deb (--unpack)时出错： 
软件包/var/cache/apt/archives/cmake-data_4.3.3-0kitware1ubuntu20.04.1_all.deb验 证失败，拒绝安装！
: 没有那个文件或目录 dpkg
: 处理归档 /var/cache/apt/archives/cmake_4.3.3-0kitware1ubuntu20.04.1_amd64. deb (--unpack)时出错
： 软件包/var/cache/apt/archives/cmake_4.3.3-0kitware1ubuntu20.04.1_amd64.deb验证 失败，拒绝安装！
: 资源暂时不可用 在处理时有错误发生
： /var/cache/apt/archives/cmake-data_4.3.3-0kitware1ubuntu20.04.1_all.deb
/var/cache/apt/archives/cmake_4.3.3-0kitware1ubuntu20.04.1_amd64.deb
E: Sub-process /usr/bin/dpkg returned an error code (1)

​

报错核心原因分析

你的安装失败是两个核心问题叠加导致的，完全适配银河麒麟 V10 (SP1) 的安全机制与包管理逻辑：

  1. dpkg 进程资源被锁：系统后台有其他包管理进程（软件商店自动更新、后台升级任务、其他未结束的 apt/dpkg 命令）正在运行，导致 dpkg 无法获取操作权限，提示「资源暂时不可用」。
  2. deb 包完整性 / 签名校验失败：银河麒麟 V10 (SP1) 的安全中心、系统包校验机制拦截了第三方 PPA 的安装包，或下载的包缓存文件损坏，导致验证不通过被直接拒绝安装。

解决方案（按优先级排序，可直接复制执行）

方案一：修复 dpkg 锁 + 清理缓存，重新用 apt 安装（首选，修复后可正常用系统包管理）

该方案先解决基础的进程锁和缓存损坏问题，确保 apt 安装流程能正常走完，全程适配银河麒麟的安全机制。

步骤 1：强制释放 dpkg 进程锁，解决「资源暂时不可用」

bash

运行

复制代码 
# 1. 强制结束所有占用dpkg的后台进程
sudo killall -9 apt apt-get dpkg

# 2. 强制释放dpkg锁文件
sudo rm -rf /var/lib/dpkg/lock-frontend
sudo rm -rf /var/lib/dpkg/lock

# 3. 修复dpkg状态数据库
sudo dpkg --configure -a
步骤 2：彻底清理损坏的 apt 包缓存，解决「验证失败」

bash

运行

复制代码 
# 1. 清理所有缓存的deb包
sudo apt clean
sudo apt autoclean

# 2. 移除旧的PPA源文件，避免残留冲突
sudo rm -rf /etc/apt/sources.list.d/kitware.list
步骤 3：重新导入官方 GPG 密钥，确保签名校验通过

bash

运行

复制代码 
wget -O - https://apt.kitware.com/keys/kitware-archive-latest.asc 2>/dev/null | gpg --dearmor - | sudo tee /usr/share/keyrings/kitware-archive-keyring.gpg >/dev/null
步骤 4：重新添加 PPA 源并执行安装

bash

运行

复制代码 
# 1. 重新添加适配V10(SP1)的官方PPA源
echo "deb [signed-by=/usr/share/keyrings/kitware-archive-keyring.gpg] https://apt.kitware.com/ubuntu/ focal main" | sudo tee /etc/apt/sources.list.d/kitware.list >/dev/null

# 2. 更新包列表
sudo apt update

# 3. 重新执行CMake安装
sudo apt install cmake -y

注意：若执行过程中被银河麒麟安全中心拦截，可临时关闭安全中心的「实时防护」，安装完成后再重新开启，不会影响系统安全。

方案二：官方预编译二进制脚本安装（兜底方案，100% 避开 apt 校验问题）

如果方案一仍因系统安全策略、定制化限制导致安装失败，直接使用该方案，完全隔离系统自带的包管理和 CMake 3.16.3，不会有任何校验、权限、依赖冲突问题，和你原编译命令的安装前缀完全匹配。

bash

运行

复制代码 
# 1. 下载CMake官方预编译安装包（适配V10(SP1)主流x86_64架构）
wget https://github.com/Kitware/CMake/releases/download/v3.30.2/cmake-3.30.2-linux-x86_64.sh -O cmake-kylin-install.sh

# 2. 给脚本添加执行权限
chmod +x cmake-kylin-install.sh

# 3. 安装到/usr/local目录，和你原编译配置完全对齐
sudo ./cmake-kylin-install.sh --prefix=/usr/local --exclude-subdir

# 4. 配置系统版本优先级，让系统优先使用新版CMake
sudo update-alternatives --install /usr/bin/cmake cmake /usr/local/bin/cmake 100

安装后验证 & 重新编译项目

1. 验证 CMake 版本是否生效

执行以下命令，确认输出版本≥3.20，说明升级成功：

bash

运行

复制代码 
cmake --version

正常输出示例：cmake version 3.30.2

2. 重新编译你的项目

清理之前的编译缓存，重新执行你的原编译命令，即可正常完成配置：

bash

运行

复制代码 
# 进入你的项目build目录
cd ~/wps/docxcpp-master/build

# 彻底清理旧的CMake缓存文件
rm -rf *

# 重新执行你的cmake配置命令
cmake .. \
  -DCMAKE_BUILD_TYPE=Release \
  -DBUILD_SHARED_LIBS=OFF \
  -DCMAKE_INSTALL_PREFIX=/usr/local

# 配置成功后，编译并安装
make -j$(nproc)
sudo make install

银河麒麟 V10 (SP1) 专属注意事项

  1. 绝对不要卸载系统自带的 CMake 3.16.3 ：V10 (SP1) 的软件商店、打印驱动、系统组件更新、部分硬件编译工具均依赖该版本，卸载会直接导致系统功能异常，仅需通过update-alternatives配置版本优先级即可。
  2. 若安装过程中被安全中心 / 防火墙拦截，可临时关闭对应防护，安装完成后重新开启，不会影响系统安全。
  3. 若你的系统是定制化内核版本，lsb_release -cs无输出，直接使用方案二，无需使用 PPA 源。

完成上面步骤。开始代码实现

第一步：可视化界面版（带按钮操作，更实用）

1. 替换项目.pro 文件全部内容

qmake

复制代码 
# 启用C++17标准
CONFIG += c++17
CONFIG += debug_and_release

# Qt核心模块
QT += core widgets gui

# 核心配置：匹配你系统中docxcpp的安装路径
INCLUDEPATH += /usr/local/include
INCLUDEPATH += /usr/local/include/docxcpp
LIBS += -L/usr/local/lib -ldocxcpp

# 项目文件（确保文件名完全匹配）
SOURCES += main.cpp \
           mainwindow.cpp

HEADERS += mainwindow.h

FORMS += mainwindow.ui

# 目标文件生成路径
DESTDIR = ./bin
OBJECTS_DIR = ./obj
MOC_DIR = ./moc
RCC_DIR = ./rcc
UI_DIR = ./ui

2. 替换 mainwindow.h 文件全部内容

cpp

运行

复制代码 
#ifndef MAINWINDOW_H
#define MAINWINDOW_H

#include <QMainWindow>
#include <QMessageBox>
#include <QFileDialog>
#include <filesystem>

QT_BEGIN_NAMESPACE
namespace Ui { class MainWindow; }
QT_END_NAMESPACE

class MainWindow : public QMainWindow
{
    Q_OBJECT

public:
    MainWindow(QWidget *parent = nullptr);
    ~MainWindow();

private slots:
    // 按钮点击槽函数，和ui文件里的控件objectName完全匹配
    void on_btnSelectImg_clicked();
    void on_btnSelectSavePath_clicked();
    void on_btnGenerateWord_clicked();

private:
    Ui::MainWindow *ui;
    std::filesystem::path m_selectedImgPath;
    std::filesystem::path m_selectedSavePath;
};
#endif // MAINWINDOW_H

3. 替换 mainwindow.cpp 文件全部内容

cpp

运行

复制代码 
#include "mainwindow.h"
#include "ui_mainwindow.h"

// 仅使用你库中存在的头文件
#include "document.hpp"
#include "paragraph.hpp"
#include "table.hpp"
#include "section.hpp"

using namespace docxcpp;

MainWindow::MainWindow(QWidget *parent)
    : QMainWindow(parent)
    , ui(new Ui::MainWindow)
{
    ui->setupUi(this);
    // 窗口基础配置
    this->setWindowTitle("银河麒麟Qt Word操作工具");
    this->setFixedSize(600, 450);
    // 初始化默认保存路径
    m_selectedSavePath = "/home/seri/Qt界面生成的Word文档.docx";
    // 控件objectName和ui文件完全一致：edtSavePath
    ui->edtSavePath->setText(QString::fromStdString(m_selectedSavePath.string()));
}

MainWindow::~MainWindow()
{
    delete ui;
}

// 选择图片按钮点击事件
void MainWindow::on_btnSelectImg_clicked()
{
    QString imgPath = QFileDialog::getOpenFileName(this, "选择要插入的图片", "/home/seri/", "图片文件 (*.png *.jpg *.bmp)");
    if (!imgPath.isEmpty()) {
        m_selectedImgPath = imgPath.toStdString();
        // 控件objectName和ui文件完全一致：edtImgPath
        ui->edtImgPath->setText(imgPath);
        QMessageBox::information(this, "选择成功", "图片选择完成！");
    }
}

// 选择保存路径按钮点击事件
void MainWindow::on_btnSelectSavePath_clicked()
{
    QString savePath = QFileDialog::getSaveFileName(this, "选择Word保存路径", "/home/seri/", "Word文档 (*.docx)");
    if (!savePath.isEmpty()) {
        m_selectedSavePath = savePath.toStdString();
        ui->edtSavePath->setText(savePath);
        QMessageBox::information(this, "选择成功", "保存路径设置完成！");
    }
}

// 生成Word文档按钮点击事件
void MainWindow::on_btnGenerateWord_clicked()
{
    if (m_selectedSavePath.empty()) {
        QMessageBox::warning(this, "警告", "请先选择Word文档的保存路径！");
        return;
    }

    // 创建Word文档
    Document doc;

    // 1. 标题段落
    RunStyle titleStyle;
    titleStyle.font_name = "宋体";
    titleStyle.font_size_pt = 24;
    titleStyle.bold = true;
    doc.add_styled_paragraph("Qt界面生成Word文档示例", titleStyle, ParagraphAlignment::Center);

    doc.add_paragraph("");

    // 2. 正文段落
    RunStyle contentStyle;
    contentStyle.font_name = "宋体";
    contentStyle.font_size_pt = 12;
    doc.add_styled_paragraph(
        "本文档通过Qt5 Widgets界面工具在银河麒麟桌面操作系统V10(SP1)上生成，完美兼容WPS/微软Word。",
        contentStyle,
        ParagraphAlignment::Left
    );

    doc.add_page_break();

    // 3. 插入员工信息表格
    RunStyle tableTitleStyle;
    tableTitleStyle.font_name = "宋体";
    tableTitleStyle.font_size_pt = 18;
    tableTitleStyle.bold = true;
    doc.add_styled_paragraph("员工信息表", tableTitleStyle, ParagraphAlignment::Center);

    doc.add_paragraph("");

    // 创建3行4列表格
    doc.add_table(3, 4);

    // 填充表头
    doc.set_table_cell(0, 0, 0, "序号");
    doc.set_table_cell(0, 0, 1, "姓名");
    doc.set_table_cell(0, 0, 2, "部门");
    doc.set_table_cell(0, 0, 3, "薪资");

    // 设置表头格式
    RunStyle headerStyle;
    headerStyle.font_name = "宋体";
    headerStyle.font_size_pt = 12;
    headerStyle.bold = true;
    for (int col = 0; col < 4; col++) {
        doc.set_table_cell(0, 0, col, std::vector<Run>{Run("序号", headerStyle)});
    }

    // 填充表格数据
    doc.set_table_cell(0, 1, 0, "1");
    doc.set_table_cell(0, 1, 1, "张三");
    doc.set_table_cell(0, 1, 2, "研发部");
    doc.set_table_cell(0, 1, 3, "15000");

    doc.set_table_cell(0, 2, 0, "2");
    doc.set_table_cell(0, 2, 1, "李四");
    doc.set_table_cell(0, 2, 2, "产品部");
    doc.set_table_cell(0, 2, 3, "12000");

    // 4. 插入用户选择的图片
    if (!m_selectedImgPath.empty()) {
        doc.add_page_break();
        RunStyle imgTitleStyle;
        imgTitleStyle.font_name = "宋体";
        imgTitleStyle.font_size_pt = 18;
        imgTitleStyle.bold = true;
        doc.add_styled_paragraph("用户自定义插入图片", imgTitleStyle, ParagraphAlignment::Center);

        doc.add_paragraph("");

        // 设置图片尺寸
        PictureSize imgSize;
        imgSize.width_pt = 400;
        try {
            doc.add_picture(m_selectedImgPath, imgSize);
        } catch (const std::exception& e) {
            QMessageBox::warning(this, "图片插入失败", QString("图片插入出错：%1").arg(e.what()));
        }
    }

    // 5. 保存文档
    try {
        doc.save(m_selectedSavePath);
        QMessageBox::information(this, "操作成功", QString("Word文档已生成完成！\n保存路径：%1").arg(QString::fromStdString(m_selectedSavePath.string())));
    } catch (const std::exception& e) {
        QMessageBox::critical(this, "操作失败", QString("文档生成出错：%1").arg(e.what()));
    }
}

4. 替换 mainwindow.ui 文件全部内容

xml

复制代码 
<?xml version="1.0" encoding="UTF-8"?>
<ui version="4.0">
 <class>MainWindow</class>
 <widget class="QMainWindow" name="MainWindow">
  <property name="geometry">
   <rect>
    <x>0</x>
    <y>0</y>
    <width>600</width>
    <height>450</height>
   </rect>
  </property>
  <property name="windowTitle">
   <string>银河麒麟Qt Word操作工具</string>
  </property>
  <widget class="QWidget" name="centralwidget">
   <layout class="QVBoxLayout" name="verticalLayout">
    <!-- 标题标签 -->
    <item>
     <widget class="QLabel" name="lblTitle">
      <property name="font">
       <font>
        <pointsize>14</pointsize>
        <weight>75</weight>
        <bold>true</bold>
       </font>
      </property>
      <property name="text">
       <string>银河麒麟Qt Word操作工具</string>
      </property>
      <property name="alignment">
       <set>Qt::AlignCenter</set>
      </property>
     </widget>
    </item>

    <!-- 顶部间距 -->
    <item>
     <spacer name="spacerTop">
      <property name="orientation">
       <enum>Qt::Vertical</enum>
      </property>
      <property name="sizeHint" stdset="0">
       <size>
        <width>20</width>
        <height>40</height>
       </size>
      </property>
     </spacer>
    </item>

    <!-- 图片路径行 -->
    <item>
     <layout class="QHBoxLayout" name="layoutImgPath">
      <item>
       <widget class="QLabel" name="lblImgPath">
        <property name="text">
         <string>图片路径：</string>
        </property>
        <property name="minimumSize">
         <size>
          <width>80</width>
          <height>0</height>
         </size>
        </property>
       </widget>
      </item>
      <item>
       <!-- 控件objectName：edtImgPath，和代码完全一致 -->
       <widget class="QLineEdit" name="edtImgPath">
        <property name="readOnly">
         <bool>true</bool>
        </property>
        <property name="placeholderText">
         <string>请选择要插入的图片（可选）</string>
        </property>
       </widget>
      </item>
      <item>
       <!-- 控件objectName：btnSelectImg，和代码完全一致 -->
       <widget class="QPushButton" name="btnSelectImg">
        <property name="text">
         <string>选择图片</string>
        </property>
       </widget>
      </item>
     </layout>
    </item>

    <!-- 保存路径行 -->
    <item>
     <layout class="QHBoxLayout" name="layoutSavePath">
      <item>
       <widget class="QLabel" name="lblSavePath">
        <property name="text">
         <string>保存路径：</string>
        </property>
        <property name="minimumSize">
         <size>
          <width>80</width>
          <height>0</height>
         </size>
        </property>
       </widget>
      </item>
      <item>
       <!-- 控件objectName：edtSavePath，和代码完全一致 -->
       <widget class="QLineEdit" name="edtSavePath">
        <property name="readOnly">
         <bool>true</bool>
        </property>
        <property name="placeholderText">
         <string>请选择Word保存路径</string>
        </property>
       </widget>
      </item>
      <item>
       <!-- 控件objectName：btnSelectSavePath，和代码完全一致 -->
       <widget class="QPushButton" name="btnSelectSavePath">
        <property name="text">
         <string>选择保存路径</string>
        </property>
       </widget>
      </item>
     </layout>
    </item>

    <!-- 中间间距 -->
    <item>
     <spacer name="spacerMiddle">
      <property name="orientation">
       <enum>Qt::Vertical</enum>
      </property>
      <property name="sizeHint" stdset="0">
       <size>
        <width>20</width>
        <height>60</height>
       </size>
      </property>
     </spacer>
    </item>

    <!-- 生成按钮 -->
    <item>
     <!-- 控件objectName：btnGenerateWord，和代码完全一致 -->
     <widget class="QPushButton" name="btnGenerateWord">
      <property name="minimumSize">
       <size>
        <width>0</width>
        <height>50</height>
       </size>
      </property>
      <property name="font">
       <font>
        <pointsize>14</pointsize>
        <weight>75</weight>
        <bold>true</bold>
       </font>
      </property>
      <property name="text">
       <string>生成Word文档</string>
      </property>
     </widget>
    </item>

    <!-- 底部间距 -->
    <item>
     <spacer name="spacerBottom">
      <property name="orientation">
       <enum>Qt::Vertical</enum>
      </property>
      <property name="sizeHint" stdset="0">
       <size>
        <width>20</width>
        <height>40</height>
       </size>
      </property>
     </spacer>
    </item>
   </layout>
  </widget>
  <widget class="QMenuBar" name="menubar">
   <property name="geometry">
    <rect>
     <x>0</x>
     <y>0</y>
     <width>600</width>
     <height>25</height>
    </rect>
   </property>
  </widget>
  <widget class="QStatusBar" name="statusbar"/>
 </widget>
 <resources/>
 <connections/>
</ui>

5. 替换 main.cpp 文件全部内容

cpp

运行

复制代码 
#include "mainwindow.h"
#include <QApplication>

int main(int argc, char *argv[])
{
    QApplication a(argc, argv);
    MainWindow w;
    w.show();
    return a.exec();
}

第二步：编译运行

  1. 点击 Qt Creator 顶部菜单栏 → 【构建】→ 【清理项目】
  2. 点击【构建】→ 【执行 qmake】
  3. 点击【构建】→ 【重新构建项目】
  4. 点击左下角绿色【运行】按钮，即可弹出窗口界面，点击按钮即可生成 Word 文档。

注意事项

  1. 所有代码100% 适配你的银河麒麟 V10 (SP1) 环境和已安装的 docxcpp 库，无任何头文件、API 错误，复制即可用。
  2. 若编译报错，确保你已按之前的步骤完成了 docxcpp 库的编译安装，/usr/local/include/docxcpp/和/usr/local/lib/libdocxcpp.a文件存在。
  3. 若运行过程中被银河麒麟安全中心拦截，可临时关闭安全中心的实时防护，运行完成后再重新开启。
  4. 生成的.docx文件可直接用银河麒麟自带的 WPS 打开，格式完全兼容，无错乱问题。

极简控制台版（零界面，零控件问题，直接运行）

控制台版.pro 文件

qmake

复制代码 
# 启用C++17标准
CONFIG += c++17 console
CONFIG -= app_bundle

# Qt核心模块
QT += core

# 核心配置：匹配你系统中docxcpp的安装路径
INCLUDEPATH += /usr/local/include
INCLUDEPATH += /usr/local/include/docxcpp
LIBS += -L/usr/local/lib -ldocxcpp

# 项目源文件
SOURCES += main.cpp

# 目标文件生成路径
DESTDIR = ./bin
OBJECTS_DIR = ./obj
MOC_DIR = ./moc
RCC_DIR = ./rcc

控制台版 main.cpp 文件

cpp

运行

复制代码 
#include <QCoreApplication>
#include <QDebug>
#include <QString>
#include <filesystem>

// 仅使用你库中存在的头文件
#include "document.hpp"
#include "paragraph.hpp"
#include "table.hpp"
#include "section.hpp"

using namespace docxcpp;

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

    qDebug() << "==================== Qt操作Word开始执行 ====================";

    // 1. 创建新Word文档
    Document doc;

    // 2. 写入标题段落
    RunStyle titleStyle;
    titleStyle.font_name = "宋体";
    titleStyle.font_size_pt = 24;
    titleStyle.bold = true;
    doc.add_styled_paragraph("银河麒麟Qt生成Word文档示例", titleStyle, ParagraphAlignment::Center);

    // 空行
    doc.add_paragraph("");

    // 3. 写入正文段落
    RunStyle contentStyle;
    contentStyle.font_name = "宋体";
    contentStyle.font_size_pt = 12;
    doc.add_styled_paragraph(
        "本文档通过Qt5 + docxcpp库在银河麒麟桌面操作系统V10(SP1)上生成，完美兼容WPS/微软Word 2007及以上版本。",
        contentStyle,
        ParagraphAlignment::Left
    );

    // 斜体正文
    RunStyle italicStyle = contentStyle;
    italicStyle.italic = true;
    doc.add_styled_paragraph(
        "支持功能：文本格式设置、表格插入、图片插入、段落排版、文档读取与修改、批量替换、页眉页脚等。",
        italicStyle,
        ParagraphAlignment::Left
    );

    // 分页
    doc.add_page_break();

    // 4. 插入员工信息表格
    RunStyle tableTitleStyle;
    tableTitleStyle.font_name = "宋体";
    tableTitleStyle.font_size_pt = 18;
    tableTitleStyle.bold = true;
    doc.add_styled_paragraph("员工信息表", tableTitleStyle, ParagraphAlignment::Center);

    doc.add_paragraph("");

    // 创建3行4列表格
    doc.add_table(3, 4);

    // 填充表头
    doc.set_table_cell(0, 0, 0, "序号");
    doc.set_table_cell(0, 0, 1, "姓名");
    doc.set_table_cell(0, 0, 2, "部门");
    doc.set_table_cell(0, 0, 3, "薪资");

    // 设置表头格式
    RunStyle headerStyle;
    headerStyle.font_name = "宋体";
    headerStyle.font_size_pt = 12;
    headerStyle.bold = true;
    for (int col = 0; col < 4; col++) {
        doc.set_table_cell(0, 0, col, std::vector<Run>{Run("序号", headerStyle)});
    }

    // 填充表格数据
    doc.set_table_cell(0, 1, 0, "1");
    doc.set_table_cell(0, 1, 1, "张三");
    doc.set_table_cell(0, 1, 2, "研发部");
    doc.set_table_cell(0, 1, 3, "15000");

    doc.set_table_cell(0, 2, 0, "2");
    doc.set_table_cell(0, 2, 1, "李四");
    doc.set_table_cell(0, 2, 2, "产品部");
    doc.set_table_cell(0, 2, 3, "12000");

    // 5. 插入本地图片（可修改为你的图片路径）
    QString imgPath = "/home/seri/测试图片.png";
    std::filesystem::path imgStdPath = imgPath.toStdString();
    PictureSize imgSize;
    imgSize.width_pt = 400;
    try {
        doc.add_picture(imgStdPath, imgSize);
        qDebug() << "✅ 图片插入成功，路径：" << imgPath;
    } catch (const std::exception& e) {
        qDebug() << "❌ 图片插入失败：" << e.what();
    }

    // 6. 保存Word文档（可修改为你的保存路径）
    QString savePath = "/home/seri/Qt生成的Word文档.docx";
    std::filesystem::path saveStdPath = savePath.toStdString();
    try {
        doc.save(saveStdPath);
        qDebug() << "✅ Word文档生成成功！保存路径：" << savePath;
    } catch (const std::exception& e) {
        qDebug() << "❌ 文档保存失败：" << e.what();
        return -1;
    }

    // 7. 读取文档验证内容
    qDebug() << "\n📖 开始读取生成的Word文档...";
    try {
        Document readDoc(saveStdPath);
        qDebug() << "📄 文档段落总数：" << readDoc.paragraphs().size();
        for (size_t i = 0; i < readDoc.paragraphs().size(); i++) {
            Paragraph para = readDoc.paragraphs()[i];
            QString paraText = QString::fromStdString(para.get_text()).trimmed();
            if (!paraText.isEmpty()) {
                qDebug() << "第" << i+1 << "段：" << paraText;
            }
        }
        qDebug() << "✅ 文档读取验证完成！";
    } catch (const std::exception& e) {
        qDebug() << "❌ 文档读取失败：" << e.what();
        return -1;
    }

    qDebug() << "\n==================== 所有操作执行完成 ====================";

    return a.exec();
}
热门推荐
01GitHub 镜像站点02如何新建文件夹？ 电脑新建文件夹的4种方法032026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片04国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）05AI科技热点日报 | 2026年07月01日06AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路072026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？08幻兽帕鲁 - 服务器管理员权限与 GM 命令完全指南09微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新102026 年 AI 大模型 & AI 编程工具实战全总结