使用Docx4j替换Word模板占位符时格式丢失问题求助

你的问题我太熟悉了——直接遍历Text元素替换内容很容易踩坑，因为Word文档的文本经常会被拆分成多个Text节点，而且格式是绑定在Run（org.docx4j.wml.R）上的，不是单个Text。给你两个靠谱的解决方案：

方案一：用Docx4j官方推荐的MailMerger工具（最省心） #

Docx4j自带的MailMerger是专门处理模板变量替换的，能自动处理文本拆分的情况，还会完整保留占位符的原始格式。

步骤： #

1. 先把Word模板里的占位符改成${tempDatum}这种格式（注意是美元符号加大括号）
2. 用下面的代码替换：

import org.docx4j.model.fields.merge.MailMerger;
import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import java.util.HashMap;
import java.util.Map;

public void replaceTemplate() throws Exception {
    // 加载模板文件
    WordprocessingMLPackage wp = WordprocessingMLPackage.load(context.getResourceAsStream("/template.docx"));
    
    // 准备替换的键值对：键是模板里的占位符（去掉${}），值是替换内容
    Map<String, String> replacements = new HashMap<>();
    replacements.put("tempDatum", "Apr. 2007 - Dez. 2012");
    
    // 执行替换，第三个参数false表示不保留原始占位符的字段代码
    MailMerger.performMerge(wp, replacements, false);
    
    // 后续可以保存或输出文档
    // wp.save(new File("output.docx"));
}

这个方法的好处是不用自己处理文本拆分和格式绑定，官方工具已经帮你搞定了，几乎不会出现格式丢失的情况。

方案二：自己实现Run级别的替换（适合自定义需求） #

如果你不想用官方工具，需要自己控制替换逻辑，那就要针对Run来处理，因为格式是存在Run的属性（RPr）里的，只要不修改Run的属性，替换文本后格式就会保留。

核心思路： #

• 遍历所有Run元素，合并同一个Run下的所有Text内容，判断是否匹配占位符
• 匹配成功后，清空Run里的原有Text，添加新的Text内容（保留Run的格式属性）

代码示例： #

import org.docx4j.openpackaging.packages.WordprocessingMLPackage;
import org.docx4j.wml.R;
import org.docx4j.wml.Text;
import java.util.List;
import java.util.stream.Collectors;

private void replacePlaceholder(WordprocessingMLPackage template, String replacementText, String placeholder) {
    // 获取文档中所有的Run元素
    List<Object> runs = template.getMainDocumentPart().getAllElementsFromObject(R.class);
    
    for (Object runObj : runs) {
        R run = (R) runObj;
        // 合并当前Run下的所有Text内容，避免文本被拆分导致匹配失败
        StringBuilder runContent = new StringBuilder();
        List<Text> textElements = run.getContent().stream()
                .filter(obj -> obj instanceof Text)
                .map(obj -> (Text) obj)
                .collect(Collectors.toList());
        
        for (Text text : textElements) {
            if (text.getValue() != null) {
                runContent.append(text.getValue());
            }
        }
        
        // 如果当前Run的内容和占位符完全匹配
        if (placeholder.equals(runContent.toString())) {
            // 清空Run里的原有Text元素
            run.getContent().removeIf(obj -> obj instanceof Text);
            // 创建新的Text元素并设置内容
            Text newText = template.getWmlObjectFactory().createText();
            newText.setValue(replacementText);
            // 把新Text添加到Run中，保留Run的原始格式
            run.getContent().add(newText);
        }
    }
}

// 调用方式和你原来的一样
WordprocessingMLPackage wp = WordprocessingMLPackage.load(context.getResourceAsStream("/template.docx"));
replacePlaceholder(wp, "Apr. 2007 - Dez. 2012", "tempDatum");

注意事项： #

• 确保模板里的占位符是一个单独的Run（选中占位符文本时，格式工具栏显示的是统一的格式，没有被拆分到多个Run里）
• 如果占位符跨多个Run，那需要更复杂的逻辑来合并多个Run的内容，但这种情况建议用方案一的MailMerger更省心

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