如何通过POI高效定位Word书签对应的XWPFRun并替换内容？

一、直接通过书签定位对应XWPFRun（保留格式） #

每个书签在OOXML结构中被<w:bookmarkStart>和<w:bookmarkEnd>包裹，针对单Run对应书签的场景，可通过书签起始节点定位相邻的Run节点：

public static XWPFRun findRunByBookmark(XWPFDocument doc, String bookmarkName) {
    // 遍历普通段落中的书签
    for (XWPFParagraph para : doc.getParagraphs()) {
        List<CTBookmark> bookmarks = para.getCTP().getBookmarkStartList();
        for (CTBookmark bookmark : bookmarks) {
            if (bookmarkName.equals(bookmark.getName())) {
                XmlObject nextSibling = bookmark.getDomNode().getNextSibling();
                // 跳过XML游标书签节点
                if (nextSibling instanceof org.apache.xmlbeans.XmlCursor.XmlBookmark) {
                    nextSibling = nextSibling.getNextSibling();
                }
                if (nextSibling != null && "w:r".equals(nextSibling.getLocalName())) {
                    CTR ctr = CTR.Factory.parse(nextSibling);
                    return new XWPFRun(ctr, para);
                }
            }
        }
    }
    // 遍历表格单元格中的书签
    for (XWPFTable table : doc.getTables()) {
        for (XWPFTableRow row : table.getRows()) {
            for (XWPFTableCell cell : row.getTableCells()) {
                for (XWPFParagraph para : cell.getParagraphs()) {
                    List<CTBookmark> bookmarks = para.getCTP().getBookmarkStartList();
                    for (CTBookmark bookmark : bookmarks) {
                        if (bookmarkName.equals(bookmark.getName())) {
                            XmlObject nextSibling = bookmark.getDomNode().getNextSibling();
                            if (nextSibling instanceof org.apache.xmlbeans.XmlCursor.XmlBookmark) {
                                nextSibling = nextSibling.getNextSibling();
                            }
                            if (nextSibling != null && "w:r".equals(nextSibling.getLocalName())) {
                                CTR ctr = CTR.Factory.parse(nextSibling);
                                return new XWPFRun(ctr, para);
                            }
                        }
                    }
                }
            }
        }
    }
    return null;
}

找到目标Run后直接修改文本，保留原有格式且不会触发异常：

XWPFRun targetRun = findRunByBookmark(doc, "name");
if (targetRun != null) {
    targetRun.setText("Ryan", 0); // 参数0表示替换原有内容，保留字体等格式
}

二、XmlValueDisconnectedException的根因及解决 #

你之前的Demo大概率是通过删除书签内原有节点再插入新内容实现替换，导致原XWPFRun对象与文档DOM树的引用断开。直接修改已有Run的文本，而非重建节点，就能彻底避免该异常。

三、大文件多书签场景的高效定位方案 #

1. 预构建书签-Run映射表：文档加载完成后，一次性遍历所有段落和表格，将书签名称与对应XWPFRun缓存到HashMap中，后续替换直接从Map取值，避免重复遍历开销：

public static Map<String, XWPFRun> buildBookmarkRunMap(XWPFDocument doc) {
    Map<String, XWPFRun> bookmarkRunMap = new HashMap<>();
    // 处理普通段落
    for (XWPFParagraph para : doc.getParagraphs()) {
        List<CTBookmark> bookmarks = para.getCTP().getBookmarkStartList();
        if (bookmarks.isEmpty()) continue;
        for (CTBookmark bookmark : bookmarks) {
            String name = bookmark.getName();
            if (bookmarkRunMap.containsKey(name)) continue;
            XmlObject nextSibling = bookmark.getDomNode().getNextSibling();
            if (nextSibling instanceof org.apache.xmlbeans.XmlCursor.XmlBookmark) {
                nextSibling = nextSibling.getNextSibling();
            }
            if (nextSibling != null && "w:r".equals(nextSibling.getLocalName())) {
                CTR ctr = CTR.Factory.parse(nextSibling);
                bookmarkRunMap.put(name, new XWPFRun(ctr, para));
            }
        }
    }
    // 处理表格单元格
    for (XWPFTable table : doc.getTables()) {
        for (XWPFTableRow row : table.getRows()) {
            for (XWPFTableCell cell : row.getTableCells()) {
                for (XWPFParagraph para : cell.getParagraphs()) {
                    List<CTBookmark> bookmarks = para.getCTP().getBookmarkStartList();
                    if (bookmarks.isEmpty()) continue;
                    for (CTBookmark bookmark : bookmarks) {
                        String name = bookmark.getName();
                        if (bookmarkRunMap.containsKey(name)) continue;
                        XmlObject nextSibling = bookmark.getDomNode().getNextSibling();
                        if (nextSibling instanceof org.apache.xmlbeans.XmlCursor.XmlBookmark) {
                            nextSibling = nextSibling.getNextSibling();
                        }
                        if (nextSibling != null && "w:r".equals(nextSibling.getLocalName())) {
                            CTR ctr = CTR.Factory.parse(nextSibling);
                            bookmarkRunMap.put(name, new XWPFRun(ctr, para));
                        }
                    }
                }
            }
        }
    }
    return bookmarkRunMap;
}

使用示例：

Map<String, XWPFRun> bookmarkMap = buildBookmarkRunMap(doc);
XWPFRun nameRun = bookmarkMap.get("name");
if (nameRun != null) {
    nameRun.setText("Ryan", 0);
}

2. 跳过无书签节点：遍历过程中先判断段落/单元格是否包含书签，无书签则直接跳过，减少无效遍历操作。

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