DocxFactory：基于 C++ 的 Word 文档生成库（无需 Office）

3. 模板设计核心技巧

基础占位符设置

在 Word 模板中使用 ${变量名} 定义动态内容。例如文本替换写为 尊敬的 ${userName}，您好！；日期格式可自定义，如 合同日期：${contractDate,yyyy-MM-dd}。

表格重复块

1. 在模板中插入表格，选中需要重复的行。
2. 在开发工具 > 书签中为该行命名（如 salesRow）。
3. 在单元格内定义占位符（如 ${product.name}、${product.price}）。

图片占位符

1. 插入临时图片，右键选择设置图片格式 > 大小与属性 > 替代文本，输入占位符名称（如 ${logo}）。
2. 确保图片位置固定，避免生成时错位。

4. 常用场景示例

以下是三个最核心的使用场景，涵盖从简单文本替换到复杂表格、图片插入。所有示例均假设项目已正确链接 DocxFactory 库及依赖。

简单文本替换

适用于批量生成带动态文本的文档，如合同中的姓名、日期、金额。 前提是在 docx 模板中定义好占位符，格式为 ${占位符名}。

#include <DocxFactory/DocxFactory.h>
#include <memory>
using namespace DocxFactory;
using namespace std;

int main() {
    try {
        // 初始化库
        Initialize::init();
        
        // 加载 docx 模板
        auto_ptr<Template> docTemplate(Template::load("template_contract.docx"));
        
        // 获取上下文用于填充
        auto_ptr<Context> context(docTemplate->getContext());
        
        // 替换占位符
        context->replace("userName", "张三");
        context->replace("contractDate", "2025-10-29");
        context->replace("contractAmount", "50000.00");
        
        // 生成最终文档
        docTemplate->generate("output_contract_张三.docx");
        
        // 清理资源
        Initialize::uninit();
        cout << "文档生成成功！" << endl;
    } catch (const Exception& e) {
        cerr << "错误：" << e.what() << endl;
        return 1;
    }
    return 0;
}

动态生成表格

适用于生成带批量数据的表格，如销售报表。前提是模板中标记了重复块（如 salesRow），并在单元格中定义了循环占位符。

#include <DocxFactory/DocxFactory.h>
#include <vector>
#include <memory>
using namespace DocxFactory;
using namespace std;

struct SalesData {
    string name;
    string sales;
};

int main() {
    try {
        Initialize::init();
        auto_ptr<Template> docTemplate(Template::load("template_sales.docx"));
        auto_ptr<Context> context(docTemplate->getContext());
        
        // 准备数据
        vector<SalesData> salesList = {
            {"产品 A", "12000 元"},
            {"产品 B", "8500 元"},
            {"产品 C", "15600 元"}
        };
        
        // 获取重复块
        auto_ptr<Repeat> repeat(context->getRepeat("salesRow"));
        
        // 循环填充
        for (const auto& data : salesList) {
            repeat->next();
            context->replace("tableData.name", data.name);
            context->replace("tableData.sales", data.sales);
        }
        
        docTemplate->generate("output_sales_report.docx");
        Initialize::uninit();
        cout << "表格文档生成成功！" << endl;
    } catch (const Exception& e) {
        cerr << "错误：" << e.what() << endl;
        return 1;
    }
    return 0;
}

插入图片

适用于生成带动态图片的文档，如证书中的 Logo。前提是模板中定义了图片占位符。

#include <DocxFactory/DocxFactory.h>
#include <memory>
using namespace DocxFactory;
using namespace std;

int main() {
    try {
        Initialize::init();
        auto_ptr<Template> docTemplate(Template::load("template_certificate.docx"));
        auto_ptr<Context> context(docTemplate->getContext());
        
        // 替换文本
        context->replace("certUserName", "李四");
        context->replace("certType", "优秀员工证书");
        
        // 插入图片（单位：Twip，1cm≈567Twip）
        context->insertImage(
            "imgLogo",
            "company_logo.png",
            3 * 567,
            2 * 567
        );
        
        docTemplate->generate("output_certificate_李四.docx");
        Initialize::uninit();
        cout << "带图片的证书生成成功！" << endl;
    } catch (const Exception& e) {
        cerr << "错误：" << e.what() << endl;
        return 1;
    }
    return 0;
}

5. 高级功能与技巧

书签替换 在 Word 中选中内容创建书签（如 target），代码中可直接替换：

context->replaceBookmark("target", "新内容");

条件判断 虽不直接支持条件标签，但可通过书签控制。例如根据条件保留或删除书签内容：

if (isPassed) {
    context->replaceBookmark("if_passed", "通过！");
} else {
    context->removeBookmark("if_passed");
}

样式控制 模板中预定义样式（如 Heading 1），代码中可动态调整：

auto_ptr<Paragraph> para = context->getParagraph("para_id");
para->setFontSize(14);
para->setBold(true);

批量优化 利用 C++11 线程库并行生成文档，或在高并发下预加载模板减少 I/O 开销。

6. 常见问题与解决方案

模板加载失败 检查路径是否正确，建议使用绝对路径。注意仅支持 .docx 格式，旧版 .doc 不兼容。

占位符未替换 核对代码中的占位符名称是否与模板完全一致（区分大小写）。建议添加 try-catch 捕获异常以便调试。

图片显示异常 确认图片格式为 PNG 或 JPEG。尺寸单位需注意 Twip 转换（1cm ≈ 567 Twip）。

7. 与其他库的对比

相比 Python 的 python-docx，DocxFactory 基于 C++ 实现，性能更高，适合嵌入高性能需求的 C++ 应用。 相比 Java 的 Apache POI，它专注于 C++ 生态，无需 JVM 依赖，部署更轻量。 相比直接操作 XML，它屏蔽了 OOXML 规范细节，显著降低开发复杂度。

8. 总结

通过本文的介绍，你可以掌握 DocxFactory 的核心用法，从模板设计到代码实现，高效完成 Word 文档的动态生成。无论是简单的文本替换还是复杂的表格图片组合，规范的模板设计都是项目成功的关键。希望这些实战经验能为你的二次开发工作提供实质性的帮助。