Apache POI 5.2.2：为已有Word文档指定文本添加注释问题

问题核心 #

你的代码主要问题在于注释范围标记（commentRangeStart/commentRangeEnd）的位置错误，以及错误地将这些标记绑定到了CTComment对象上。Word的注释范围是属于段落（CTP）的层级标记，需要精准包裹目标文本所在的Run，而非与前后文本的Run关联。

修正步骤说明 #

1. 拆分原Run为三个部分：目标文本前的内容、目标文本、目标文本后的内容
2. 在目标文本Run的前面插入commentRangeStart
3. 插入目标文本Run
4. 在目标文本Run的后面插入commentRangeEnd
5. 在commentRangeEnd后添加注释引用（commentReference）
6. 无需给CTComment设置commentRangeStartArray或commentRangeEndArray，这些标记属于段落，不是注释对象的属性

修正后的代码片段 #

if(paragraph.getText().contains(action.getOriginalText())){
    for(int runIndex = internalParagraphRunIndex; runIndex < paragraph.getRuns().size(); runIndex++) {
        XWPFRun run = paragraph.getRuns().get(runIndex);

        if (run.text().equals(action.getOriginalText())) {
            throw new RuntimeException("Not yet implemented");
        } else if (run.text().contains(action.getOriginalText())) {
            System.out.println("Part of the run needs to be annotated");
            XWPFComments comments = wordDocument.getDocComments();
            CTComments existingCtComments = comments.getCtComments();

            // 创建CTComment并设置基础属性
            CTComment newCTComment = existingCtComments.addNewComment();
            String commentId = getCommentId(existingCtComments);
            newCTComment.setId(commentId);
            
            XWPFComment newComment = new XWPFComment(newCTComment, comments);
            newComment.setAuthor("Teradactor");
            newComment.setDate(new GregorianCalendar());
            newComment.setInitials("TD");
            newComment.createParagraph().createRun().setText(action.getAnnotationText());
            comments.createComment(BigInteger.valueOf(Long.parseLong(commentId)));

            // 拆分Run文本
            String[] splittedText = splitRunTextIntoParts(run, action.getOriginalText());
            int targetIndex = findLocationOfTextInSplittedText(splittedText, action.getOriginalText());
            
            if (targetIndex == -1) {
                throw new RuntimeException("The text that needs to be annotated is not found in the splitted run.");
            }

            // 插入拆分后的Run并配置注释范围
            int insertOffset = 0;
            for (int z = 0; z < splittedText.length; z++) {
                if (z == targetIndex) {
                    // 1. 在目标文本前插入注释起始标记
                    paragraph.getCTP().addNewCommentRangeStart().setId(commentId);
                    
                    // 2. 插入目标文本Run
                    XWPFRun targetRun = paragraph.insertNewRun(runIndex + z + insertOffset);
                    targetRun.setText(splittedText[z]);
                    // 保留原Run样式（如果需要）
                    copyRunStyle(run, targetRun);
                    
                    // 3. 在目标文本后插入注释结束标记
                    paragraph.getCTP().addNewCommentRangeEnd().setId(commentId);
                    
                    // 4. 添加注释引用（单独的Run或绑定到目标Run都可，这里用单独Run更标准）
                    XWPFRun refRun = paragraph.insertNewRun(runIndex + z + insertOffset + 1);
                    refRun.getCTR().addNewCommentReference().setId(commentId);
                    insertOffset++; // 因为多插入了一个引用Run，后续索引需要偏移
                } else {
                    // 插入前后的普通文本Run
                    XWPFRun normalRun = paragraph.insertNewRun(runIndex + z + insertOffset);
                    normalRun.setText(splittedText[z]);
                    // 保留原Run样式
                    copyRunStyle(run, normalRun);
                }
            }

            // 删除原Run
            paragraph.removeRun(runIndex + splittedText.length + insertOffset);
            
            // 更新后续处理的索引
            setInternalParagraphRunIndex(runIndex + splittedText.length + insertOffset + 1);
            setActionFound(true);
            break;
        }
    }
}

// 辅助方法：复制Run的样式
private void copyRunStyle(XWPFRun source, XWPFRun target) {
    target.setBold(source.isBold());
    target.setItalic(source.isItalic());
    target.setUnderline(source.getUnderline());
    target.setFontSize(source.getFontSize());
    target.setFontFamily(source.getFontFamily());
    // 按需添加更多样式属性
}

关键修正点 #

• 将commentRangeStart和commentRangeEnd精准包裹目标文本Run，确保标记位置在目标文本的前后
• 移除了错误的newCTComment.setCommentRangeStartArray和newCTComment.setCommentRangeEndArray调用，这些标记属于段落而非注释对象
• 添加了样式复制方法，保证拆分后的文本和原Run样式一致
• 注释引用单独放在一个Run中，符合Word的XML结构规范

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