DocxFactory: 基于 C++ 的 Word 文档处理库（无 Office 依赖）

编译并运行，若输出版本号则安装成功。

3.模板设计核心技巧

1.基础占位符设置

在 Word 模板中使用 ${变量名} 定义动态内容：

• 文本替换：尊敬的 ${userName}，您好！
• 日期格式：合同日期：${contractDate,yyyy-MM-dd}（支持自定义格式）。

2.表格重复块

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

3.图片占位符

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

4.常用场景示例

以下是 DocxFactory 最常用的 3 类核心场景示例，涵盖从简单文本替换到复杂表格、图片插入，代码均包含关键步骤注释，可直接参考适配。所有示例需先确保项目已正确链接 DocxFactory 库和依赖（如 libxml2）。

4.1.示例 1：简单文本替换（基础场景）

用途：批量生成带动态文本的文档（如合同、通知中的姓名、日期、金额）

前提：需先在 docx 模板中定义占位符，格式为 ${占位符名}（如模板中写 ${userName} ${contractDate}）。

#include <DocxFactory/DocxFactory.h>
#include <memory> // 用于智能指针管理资源
using namespace DocxFactory;
using namespace std;

int main() {
    try {
        // 1. 初始化 DocxFactory 库
        Initialize::init();
        
        // 2. 加载 docx 模板（替换为你的模板路径）
        auto_ptr<Template> docTemplate(Template::load("template_contract.docx"));
        
        // 3. 获取模板的'数据替换上下文'，用于填充占位符
        auto_ptr<Context> context(docTemplate->getContext());
        
        // 4. 替换模板中的占位符（key 对应模板中的 ${key}，value 为替换内容）
        context->replace("userName", "张三");       // 文本替换
        context->replace("contractDate", "2025-10-29"); // 日期替换
        context->replace("contractAmount", "50000.00"); // 数字替换
        
        // 5. 生成最终文档（替换为你的输出路径）
        docTemplate->generate("output_contract_张三.docx");
        
        // 6. 清理资源（智能指针自动释放，也可手动 delete）
        Initialize::uninit();
        cout << "文档生成成功！" << endl;
    } catch (const Exception& e) {
        // 捕获库抛出的异常（如模板不存在、占位符未找到）
        cerr << "错误：" << e.what() << endl;
        return 1;
    }
    return 0;
}

4.2.示例 2：动态生成表格（结构化数据场景）

用途：生成带批量数据的表格（如销售报表、员工名单）

前提：模板中需先插入一个表格，并在表格行的单元格中定义'重复占位符'（如 ${tableData.name} ${tableData.sales}），表示这一行需要循环生成。

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

// 定义表格数据结构（与模板占位符对应）
struct SalesData {
    string name;   // 对应模板 ${tableData.name}
    string sales;  // 对应模板 ${tableData.sales}
};

int main() {
    try {
        Initialize::init();
        auto_ptr<Template> docTemplate(Template::load("template_sales.docx")); // 实际为 docx 模板
        auto_ptr<Context> context(docTemplate->getContext());
        
        // 1. 准备表格数据（模拟从数据库/接口获取）
        vector<SalesData> salesList = {
            {"产品 A", "12000 元"},
            {"产品 B", "8500 元"},
            {"产品 C", "15600 元"}
        };
        
        // 2. 获取模板中表格的'重复块'（需先在模板中标记表格行为重复块，名称为'salesRow'）
        auto_ptr<Repeat> repeat(context->getRepeat("salesRow"));
        
        // 3. 循环填充表格行
        for (const auto& data : salesList) {
            repeat->next();              // 新建一行
            context->replace("tableData.name", data.name);   // 填充单元格 1
            context->replace("tableData.sales", data.sales); // 填充单元格 2
        }
        
        // 4. 生成文档
        docTemplate->generate("output_sales_report.docx");
        Initialize::uninit();
        cout << "表格文档生成成功！" << endl;
    } catch (const Exception& e) {
        cerr << "错误：" << e.what() << endl;
        return 1;
    }
    return 0;
}

4.3.示例 3：插入图片（含资源场景）

用途：生成带动态图片的文档（如证书中的 logo、报告中的图表）

前提：模板中需定义图片占位符（插入一个临时图片，命名为 ${imgLogo}，后续代码会替换该位置的图片）。

#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());
        
        // 1. 替换文本占位符（证书基础信息）
        context->replace("certUserName", "李四");
        context->replace("certType", "优秀员工证书");
        
        // 2. 插入图片（参数：占位符名、图片路径、图片宽度/高度，单位为缇 Twip，1cm≈567Twip）
        // 这里将模板中 ${imgLogo} 位置替换为公司 logo，宽 3cm、高 2cm
        context->insertImage(
            "imgLogo",          // 模板中的图片占位符名
            "company_logo.png", // 本地图片路径（绝对路径或相对路径）
            3 * 567,            // 宽度：3cm 转换为 Twip
            2 * 567             // 高度：2cm 转换为 Twip
        );
        
        // 3. 生成最终证书
        docTemplate->generate("output_certificate_李四.docx");
        Initialize::uninit();
        cout << "带图片的证书生成成功！" << endl;
    } catch (const Exception& e) {
        cerr << "错误：" << e.what() << endl;
        return 1;
    }
    return 0;
}

5.高级功能与技巧

1.书签替换

• 创建书签：在 Word 中选中内容，点击插入 > 书签，命名为 target。
• 代码替换：

context->replaceBookmark("target", "新内容"); // 替换书签内容

2.条件判断（间接实现）

DocxFactory 不直接支持条件标签，但可通过以下方式实现：

1. 在模板中为需条件显示的内容添加书签（如 if_passed）。
2. 在代码中根据条件删除或保留书签内容：

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

3.样式与格式控制

• 应用模板样式：在模板中预定义样式（如 Heading 1），代码中无需额外设置。
• 动态调整格式：

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

4.批量生成优化

• 多线程处理：使用 C++11 线程库并行生成多个文档。
• 预加载模板：在高并发场景下，提前加载模板到内存中以减少 I/O 开销。

6.常见问题与解决方案

1.模板加载失败

• 检查路径：确保模板文件路径正确，建议使用绝对路径。
• 文件格式：仅支持 .docx 格式，不兼容旧版 .doc。

2.占位符未替换

• 检查名称：确保代码中的占位符名称与模板完全一致（区分大小写）。
• 异常捕获：添加 try-catch 块捕获 Exception 异常：

try {
    // 代码逻辑
} catch (const Exception& e) {
    std::cerr << "错误：" << e.what() << std::endl;
}

3.图片显示异常

• 格式支持：仅支持 PNG、JPEG 格式。
• 尺寸单位：使用缇（Twip）时需正确转换（1cm ≈ 567 Twip）。

7.与其他库的对比

• 相比 Python 的 python-docx：DocxFactory 基于 C++，性能更高，适合嵌入到高性能需求的 C++ 应用（如客户端软件、服务器程序）；
• 相比 Java 的 Apache POI：专注于 C++ 生态，无需 JVM 依赖，适合轻量级部署；
• 相比直接操作 XML：屏蔽了 OOXML 规范的细节，降低开发复杂度。

8.总结

通过以上介绍，你可高效设计出兼容、美观的 DocxFactory 模板，结合代码实现动态文档生成。从简单文本替换到复杂条件判断，模板设计的规范性是项目成功的关键。