Java Word模板POI生成文件

什么是Apache POI？

Apache POI 是一个开源的Java库，用于操作Microsoft Office格式文件。它支持读写Excel、Word、PowerPoint等文件格式，是Java生态中最流行的办公文档处理工具。

在生成Word文档的场景中，POI的XWPF组件（org.apache.poi.xwpf）专门用于处理.docx格式文件。

为什么使用模板生成Word文件？

直接使用POI API逐行构建文档代码复杂且难以维护。使用模板方式可以：

• 预先设计好文档样式、布局和格式
• 在Word中编辑模板，所见即所得
• 通过占位符替换动态内容
• 提高开发效率，降低出错概率
• 便于与非技术人员协作（如产品经理、设计师）

基本实现原理

模板设计

在Word文档中使用特定占位符，如：${姓名}、${日期}、${金额}等。

Java处理流程

1. 加载模板文件（.docx）
2. 遍历文档中的段落和表格
3. 查找并替换占位符为实际数据
4. 保存为新的Word文件

// 简单示例代码
XWPFDocument document = new XWPFDocument(OPCPackage.open("template.docx"));

// 遍历所有段落
for (XWPFParagraph paragraph : document.getParagraphs()) {
    List runs = paragraph.getRuns();
    String text = paragraph.getText();
    if (text.contains("${姓名}")) {
        String newText = text.replace("${姓名}", "张三");
        paragraph.getRuns().get(0).setText(newText, 0);
    }
}

// 保存文件
FileOutputStream out = new FileOutputStream("output.docx");
document.write(out);
out.close();
document.close();

高级功能

动态表格生成

支持在模板中定义表格结构，程序动态填充行数据。

图片插入

从数据库或文件系统读取图片，插入到指定位置。

条件内容显示

根据业务逻辑决定是否显示某些段落或章节。

循环数据处理

处理列表数据，如订单明细、员工列表等。

最佳实践建议

• 使用清晰的占位符命名规则
• 模板文件与代码分离，便于维护
• 处理异常情况（如占位符未找到）
• 注意中文字符编码问题
• 大文件生成时注意内存管理
• 生成后进行格式验证