Java 进阶：基于模板生成 Word 文档的实践思路

在日常的企业级开发中，自动生成业务报表、合同文书或通知函是较为常见的需求。通过代码从模板中读取数据并填充，能减少重复性的人工操作。

虽然 Java 生态中存在 Apache POI、docx4j 等操作 Word 的库，但不同库在 API 设计、内存占用以及对特定格式的兼容性上存在差异。本文介绍使用 Spire.Doc for Java 库实现模板生成的一种方案，并展示其基本操作流程。

模板方案的优势

一种较为常见的实践是"代码硬编码"文档内容，即手动创建段落和表格。这种做法虽然直接，但文档样式的任何微调都可能涉及代码修改与重新部署。

相比之下，"模板方案"的逻辑是：提前在 Word 文件中设计好格式与排版，在需要填充数据的位置做好标记（如占位符或书签），然后在 Java 后台读取模板，替换数据并生成新文档。这种方式将样式设计与业务逻辑分离，有助于降低维护成本。

环境配置

开始编码前，需要在项目中引入 Spire.Doc for Java。

如果使用 Maven ，可在 pom.xml 中配置仓库和依赖：

xml 复制代码

<repositories>
    <repository>
        <id>com.e-iceblue</id>
        <name>e-iceblue</name>
        <url>https://repo.e-iceblue.cn/repository/maven-public/</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>e-iceblue</groupId>
        <artifactId>spire.doc</artifactId>
        <version>14.6.0</version>
    </dependency>
</dependencies>

如果不使用 Maven，也可以直接下载 Jar 包并手动引入项目。

方法一：文本替换

这是一种较为直观的方法。在 Word 模板中定义好特殊文本标记（例如 {姓名}、{日期} 或 #Name#），然后在 Java 代码中读取文档，使用 replace 方法将这些标记替换为真实数据。

适用场景： 结构相对简单的报告、信函生成。 优点： 实现逻辑简单，无需在 Word 中做额外设置。 缺点： 面对复杂的表格循环或嵌套结构时处理能力有限。

代码示例：

java 复制代码

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import java.util.HashMap;
import java.util.Map;

public class ReplaceTextDemo {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("template.docx");

        Map<String, String> dataMap = new HashMap<>();
        dataMap.put("{name}", "张三");
        dataMap.put("{date}", "2026-06-09");
        dataMap.put("{position}", "Java 开发工程师");

        for (Map.Entry<String, String> entry : dataMap.entrySet()) {
            // 参数依次为：查找文本、替换文本、是否区分大小写、是否全字匹配
            document.replace(entry.getKey(), entry.getValue(), true, true);
        }

        document.saveToFile("output/GeneratedReport.docx", FileFormat.Docx);
        document.dispose();
    }
}

方法二：书签操作

对于结构更复杂的文档，使用 Word 原生支持的书签功能是定位更精确的选择。可在 Word 模板中将光标定位到需要插入数据的位置并插入书签，然后在代码中定位该书签并填入内容。

适用场景： 合同文书生成、格式固定的复杂报表。 优点： 定位精确，不会误替换文档中的其他相同文本，支持保留书签以便后续修改。 缺点： 需要提前在 Word 源文件中定义书签，增加了模板制作的前置操作。

代码示例：

java 复制代码

import com.spire.doc.Document;
import com.spire.doc.FileFormat;
import com.spire.doc.BookmarksNavigator;
import java.util.HashMap;
import java.util.Map;

public class ReplaceBookmarkDemo {
    public static void main(String[] args) {
        Document document = new Document();
        document.loadFromFile("ContractTemplate.docx");

        BookmarksNavigator navigator = new BookmarksNavigator(document);

        Map<String, String> bookmarkData = new HashMap<>();
        bookmarkData.put("PartyA", "某某科技有限公司");
        bookmarkData.put("Amount", "人民币壹万元整");

        for (Map.Entry<String, String> entry : bookmarkData.entrySet()) {
            navigator.moveToBookmark(entry.getKey());
            // 第二个参数为 true 时表示替换后保留书签
            navigator.replaceBookmarkContent(entry.getValue(), true);
        }

        document.saveToFile("output/Contract_Final.docx", FileFormat.Docx);
        document.dispose();
    }
}

图片与表格的补充处理

实际业务中，仅替换文本可能不足以满足需求。该库也提供了操作图片和表格的 API。

例如，需要将签名图片插入模板时，可以先查找特定的文本占位符（如 [签名]），获取对应的 TextRange，再将其替换为 DocPicture 对象。对于表格，可以通过 getTable 方法获取表格对象，然后遍历行与列进行动态写入。

跨平台环境

一个值得注意的特性是，该库不依赖 Microsoft Office COM 组件，因此可以在 Windows、Linux 及 macOS 上运行。在服务器部署场景（如 Docker 容器或特定配置的 Linux 环境）中，这有助于减少因缺少 Office 环境而可能出现的兼容性问题。

结语

以上介绍了基于模板生成 Word 文档的常见思路。文本替换法实现简单，适合纯文本内容的填充场景；书签操作法定位精准，适合结构复杂、对替换准确性要求较高的正式文档。开发者可根据实际业务需求选择合适的方法。此外，该库还支持将生成的 Word 文档保存为 PDF 或 HTML 等格式，可用于文档归档或在线预览场景的后续处理。