使用Apache POI的MergeField替换DOCX占位符后引号残留问题

问题根源 #

残留的引号大概率来自MergeField的字段代码本身——Word插入MergeField时默认会给占位符加上引号（比如{ MERGEFIELD "UserName" \* MERGEFORMAT }），如果替换逻辑只更新了字段的显示文本，没清理字段代码里的引号，就会导致切换到「显示字段代码」模式时引号残留，甚至部分场景下显示文本也会带引号。

核心解决思路 #

处理MergeField时，需要同时更新字段的显示文本和字段的内部代码结构，彻底移除代码中的引号及冗余格式指令。

具体实现代码 #

import org.apache.poi.xwpf.usermodel.*;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.*;

import java.io.FileInputStream;
import java.io.FileOutputStream;
import java.util.HashMap;
import java.util.Map;

public class MergeFieldReplacer {
    public static void replaceMergeFields(XWPFDocument doc, Map<String, String> replacements) {
        // 处理普通段落
        for (XWPFParagraph para : doc.getParagraphs()) {
            processParagraph(para, replacements);
        }
        // 处理表格内段落
        for (XWPFTable table : doc.getTables()) {
            for (XWPFTableRow row : table.getRows()) {
                for (XWPFTableCell cell : row.getTableCells()) {
                    for (XWPFParagraph para : cell.getParagraphs()) {
                        processParagraph(para, replacements);
                    }
                }
            }
        }
    }

    private static void processParagraph(XWPFParagraph para, Map<String, String> replacements) {
        int pos = 0;
        while (pos < para.getRuns().size()) {
            XWPFRun run = para.getRuns().get(pos);
            String text = run.getText(0);
            if (text != null && text.contains("MERGEFIELD")) {
                XWPFField field = para.getField(pos);
                if (field != null && field.getType() == XWPFFieldType.MERGEFIELD) {
                    // 提取占位符名称并去掉前后引号
                    String fieldName = field.getFieldName().replaceAll("^\"|\"$", "");
                    String replacementText = replacements.getOrDefault(fieldName, fieldName);

                    // 更新字段显示文本
                    run.setText(replacementText, 0);

                    // 清理字段代码中的引号和冗余格式指令
                    CTFldSimple ctFldSimple = field.getCTFldSimple();
                    String instr = ctFldSimple.getInstr();
                    String newInstr = instr.replaceAll("MERGEFIELD \"([^\"]+)\"", "MERGEFIELD $1")
                            .replaceAll(" \\\\* MERGEFORMAT", "");
                    ctFldSimple.setInstr(newInstr);

                    // 删除后续关联的字段结束标记Run
                    while (pos + 1 < para.getRuns().size()) {
                        XWPFRun nextRun = para.getRuns().get(pos + 1);
                        String nextText = nextRun.getText(0);
                        if (nextText != null && (nextText.contains("\\* MERGEFORMAT") || nextText.equals("}"))) {
                            para.removeRun(pos + 1);
                        } else {
                            break;
                        }
                    }
                }
            }
            pos++;
        }
    }

    public static void main(String[] args) throws Exception {
        try (XWPFDocument doc = new XWPFDocument(new FileInputStream("input.docx"))) {
            Map<String, String> replacements = new HashMap<>();
            replacements.put("UserName", "张三");
            replacements.put("OrderNo", "ORD20240520");

            replaceMergeFields(doc, replacements);

            try (FileOutputStream out = new FileOutputStream("output.docx")) {
                doc.write(out);
            }
        }
    }
}

关键注意点 #

• 清理字段指令：通过正则替换MERGEFIELD "([^\"]+)"为MERGEFIELD $1，彻底移除字段代码中的引号。
• 移除冗余格式标记：默认的MergeField会带\* MERGEFORMAT指令，清理后可避免不必要的格式干扰。
• 处理字段结束标记：MergeField通常由多个Run组成（字段开头、指令、结束标记），替换后需删除多余Run，避免残留垃圾文本。
• 全文档遍历：覆盖普通段落、表格单元格等所有区域，确保所有MergeField都被处理。

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