如何使用Apache POI修改Word只读XWPFSDT的<w:sdt> XML内容

你提出的「保留<w:sdt>节点其余结构，仅替换<w:sdtContent>区段内容」的方案完全可行，也是POI操作Word内容控件替换的标准实现思路，不会出现节点脱离文档结构、文档损坏的问题。

你之前遇到的两类问题都可以通过直接操作POI底层绑定的XML节点树解决，不需要抽离节点转独立字符串：

• 标识匹配：每个内容控件的标题存储在<w:sdt>下的<w:sdtPr>属性节点中，对应<w:alias>节点的w:val属性值，直接读取该值即可和数据库字段做映射，等效于之前的Merge Token匹配逻辑
• 替换规则：匹配到对应字段值后，不改动<w:sdtPr>等其他节点，仅清空<w:sdtContent>内部的原有子节点，写入新的文本内容即可，控件的原有属性、样式、交互限制都会完整保留
• 遍历范围：内容控件可能出现在正文段落、表格单元格、页眉页脚等多个位置，需要递归遍历所有文档节点，避免遗漏

import org.apache.poi.ooxml.POIXMLTypeLoader;
import org.apache.poi.xwpf.usermodel.*;
import org.apache.xmlbeans.XmlObject;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.*;

import java.util.List;
import java.util.Map;

public class WordSdtReplacer {

    public static void replaceAllSdtContent(XWPFDocument doc, Map<String, String> fieldValueMap) {
        // 处理正文级节点
        processBodyElements(doc.getBodyElements(), fieldValueMap);
        // 处理页眉页脚中的内容控件
        for (XWPFHeader header : doc.getHeaderList()) {
            processBodyElements(header.getBodyElements(), fieldValueMap);
        }
        for (XWPFFooter footer : doc.getFooterList()) {
            processBodyElements(footer.getBodyElements(), fieldValueMap);
        }
    }

    private static void processBodyElements(List<IBodyElement> elements, Map<String, String> fieldValueMap) {
        for (IBodyElement element : elements) {
            if (element instanceof XWPFSDT) {
                // 处理块级内容控件
                CTSdtBlock sdtBlock = ((XWPFSDT) element).getCTSdt();
                handleBlockSdt(sdtBlock, fieldValueMap);
            } else if (element instanceof XWPFParagraph) {
                // 处理段落内的行内内容控件
                XWPFParagraph para = (XWPFParagraph) element;
                CTP ctPara = para.getCTP();
                List<CTSdtRun> sdtRuns = ctPara.getSdtList();
                for (CTSdtRun sdtRun : sdtRuns) {
                    handleRunSdt(sdtRun, fieldValueMap);
                }
            } else if (element instanceof XWPFTable) {
                // 递归处理表格内的节点
                XWPFTable table = (XWPFTable) element;
                for (XWPFTableRow row : table.getRows()) {
                    for (XWPFTableCell cell : row.getTableCells()) {
                        processBodyElements(cell.getBodyElements(), fieldValueMap);
                    }
                }
            }
        }
    }

    private static void handleBlockSdt(CTSdtBlock sdtBlock, Map<String, String> fieldValueMap) {
        CTSdtPr sdtPr = sdtBlock.getSdtPr();
        if (sdtPr == null) return;
        CTSdtAlias alias = sdtPr.getAlias();
        if (alias == null) return;
        String controlTitle = alias.getVal();
        if (!fieldValueMap.containsKey(controlTitle)) return;
        String targetValue = fieldValueMap.get(controlTitle);

        CTSdtContentBlock sdtContent = sdtBlock.getSdtContent();
        // 清空原有内容
        sdtContent.set(new XmlObject[0]);
        // 写入新文本，如需保留原格式可遍历原有<w:t>节点替换值，无需全量重建
        CTP newPara = CTP.Factory.newInstance();
        CTR newRun = newPara.addNewR();
        newRun.addNewT().setStringValue(targetValue);
        sdtContent.set(new XmlObject[]{newPara});
    }

    private static void handleRunSdt(CTSdtRun sdtRun, Map<String, String> fieldValueMap) {
        CTSdtPr sdtPr = sdtRun.getSdtPr();
        if (sdtPr == null) return;
        CTSdtAlias alias = sdtPr.getAlias();
        if (alias == null) return;
        String controlTitle = alias.getVal();
        if (!fieldValueMap.containsKey(controlTitle)) return;
        String targetValue = fieldValueMap.get(controlTitle);

        CTSdtContentRun sdtContent = sdtRun.getSdtContent();
        // 清空原有内容
        sdtContent.set(new XmlObject[0]);
        // 写入新文本
        CTR newRun = CTR.Factory.newInstance();
        newRun.addNewT().setStringValue(targetValue);
        sdtContent.set(new XmlObject[]{newRun});
    }
}

• 不要调用节点的detach()方法，也不要把节点从父节点移除后转字符串操作，直接在原节点引用上修改就不会出现节点脱离文档结构的问题
• 如果原有内容控件内存在多格式文本、图片、嵌套表格等复杂内容，不需要清空全部子节点，只需要遍历<w:sdtContent>下所有<w:t>文本节点，替换节点的字符串值即可，原有样式会完整保留
• POI 4.x及以下版本的CTSdt相关API存在部分命名空间缺失问题，建议升级到5.x以上稳定版使用，避免生成的文档打开报错
• 如果需要处理复选框、日期选择器等特殊类型的内容控件，只需要在对应处理方法里加对应类型的节点写入逻辑即可，整体遍历框架不需要调整

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