基于Java17+与docx4j实现Word模板多行数据填充的更优方案问询

针对Java 17+环境下使用docx4j处理Word模板的需求（页眉含${creationDate}占位符、正文表格需批量填充多行人员数据），以下是更高效的实现方案，核心优化点在于减少文档遍历次数、复用模板行结构：

一、核心依赖（Maven） #

确保引入适配Java 17的docx4j版本：

<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-JAXB-ReferenceImpl</artifactId>
    <version>11.4.11</version>
</dependency>
<dependency>
    <groupId>org.docx4j</groupId>
    <artifactId>docx4j-core</artifactId>
    <version>11.4.11</version>
</dependency>

二、页眉占位符替换优化 #

直接定位到页眉节点进行替换，避免全文档遍历：

private static void replaceHeaderPlaceholder(WordprocessingMLPackage wordMLPackage, String placeholder, String value) throws Exception {
    List<HeaderPart> headerParts = wordMLPackage.getHeaderParts();
    for (HeaderPart headerPart : headerParts) {
        List<Object> content = headerPart.getContent();
        for (Object obj : content) {
            if (obj instanceof P paragraph) {
                for (Object runObj : paragraph.getContent()) {
                    if (runObj instanceof R run) {
                        for (Object textObj : run.getContent()) {
                            if (textObj instanceof Text text) {
                                String contentText = text.getValue();
                                if (contentText.contains(placeholder)) {
                                    text.setValue(contentText.replace(placeholder, value));
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

三、表格批量填充优化 #

通过克隆模板行实现批量插入，避免重复创建行结构：

private static void fillTableWithData(WordprocessingMLPackage wordMLPackage, List<Person> personList) throws Exception {
    MainDocumentPart mainDocPart = wordMLPackage.getMainDocumentPart();
    List<Object> docContent = mainDocPart.getContent();

    Tbl targetTable = null;
    Tr templateRow = null;
    for (Object obj : docContent) {
        if (obj instanceof Tbl table) {
            targetTable = table;
            for (Object rowObj : targetTable.getContent()) {
                if (rowObj instanceof Tr row) {
                    String rowText = XmlUtils.marshaltoString(row, true);
                    if (rowText.contains("${id}") && rowText.contains("${firstName}")) {
                        templateRow = row;
                        break;
                    }
                }
            }
            break;
        }
    }

    if (targetTable == null || templateRow == null) {
        throw new IllegalArgumentException("未找到目标表格或模板行");
    }

    targetTable.getContent().remove(templateRow);

    for (Person person : personList) {
        Tr newRow = (Tr) XmlUtils.deepCopy(templateRow);
        replaceRowPlaceholders(newRow, person);
        targetTable.getContent().add(newRow);
    }
}

private static void replaceRowPlaceholders(Tr row, Person person) {
    for (Object cellObj : row.getContent()) {
        if (cellObj instanceof Tc cell) {
            for (Object paraObj : cell.getContent()) {
                if (paraObj instanceof P paragraph) {
                    for (Object runObj : paragraph.getContent()) {
                        if (runObj instanceof R run) {
                            for (Object textObj : run.getContent()) {
                                if (textObj instanceof Text text) {
                                    String value = text.getValue();
                                    value = value.replace("${id}", person.getId())
                                                .replace("${firstName}", person.getFirstName())
                                                .replace("${lastName}", person.getLastName())
                                                .replace("${age}", String.valueOf(person.getAge()))
                                                .replace("${gender}", person.getGender());
                                    text.setValue(value);
                                }
                            }
                        }
                    }
                }
            }
        }
    }
}

static class Person {
    private String id;
    private String firstName;
    private String lastName;
    private int age;
    private String gender;

    // 构造器、getter/setter省略
}

四、主调用示例 #

public static void main(String[] args) throws Exception {
    WordprocessingMLPackage wordMLPackage = WordprocessingMLPackage.load(new File("template.docx"));

    replaceHeaderPlaceholder(wordMLPackage, "${creationDate}", LocalDate.now().format(DateTimeFormatter.ISO_DATE));

    List<Person> personList = Arrays.asList(
        new Person("1", "John", "Doe", 30, "Male"),
        new Person("2", "Jane", "Smith", 28, "Female"),
        new Person("3", "Bob", "Johnson", 35, "Male")
    );

    fillTableWithData(wordMLPackage, personList);

    wordMLPackage.save(new File("output.docx"));
}

优化说明 #

• 页眉替换：直接定位页眉节点，仅遍历页眉内容，避免全文档扫描，大文档场景下性能提升明显
• 表格填充：通过XmlUtils.deepCopy克隆模板行，复用原有行的样式和结构，减少DOM操作次数
• 占位符替换：针对文本节点精准替换，不破坏文档原有格式和样式

内容的提问来源于stack exchange，提问作者Rando Shtishi