一、需求背景

在實際工作中，我們經常需要將多個Word文檔合并成一個文件。但當文檔中包含批注（Comments）時，傳統的復制粘貼會導致批注丟失或引用錯亂。本文將介紹如何通過Java和Apache POI庫實現保留批注及引用關系的文檔合并功能。

二、技術選型

核心依賴：

<dependency><groupId>org.apache.poi</groupId><artifactId>poi-ooxml</artifactId><version>5.3.0</version> <!-- 建議使用最新版本 -->
</dependency>
<dependency><groupId>org.apache.poi</groupId><artifactId>poi-ooxml-full</artifactId><version>5.3.0</version>
</dependency>

三、實現原理詳解

核心思路

1. 創建目標文檔作為合并容器
2. 遍歷每個源文檔的段落
3. 重建批注映射關系（避免ID沖突）
4. 復制段落內容并更新批注引用
5. 保存合并后的文檔

關鍵代碼解析

public static void mergeDocuments(List<String> sourcePaths, String outputPath) throws Exception {// 參數校驗if (sourcePaths == null || sourcePaths.isEmpty()) {throw new IllegalArgumentException("sourcePaths is empty");}// 1. 創建目標文檔var targetDoc = new XWPFDocument();// 創建批注容器（重要！）var targetComments = targetDoc.createComments();// 批注ID計數器（從0開始）BigInteger nextCommentId = BigInteger.ZERO;for (String sourceFile : sourcePaths) {try (var srcDoc = new XWPFDocument(new FileInputStream(sourceFile))) {// 2. 遍歷每個段落for (var sourcePara : srcDoc.getParagraphs()) {var newPara = targetDoc.createParagraph();// 3. 批注ID映射表（舊ID -> 新ID）Map<BigInteger, BigInteger> commentIdMap = new HashMap<>();// 4. 處理含批注引用的文本for (var sourceRun : sourcePara.getRuns()) {if (sourceRun.getCTR().sizeOfCommentReferenceArray() <= 0) {continue; // 跳過無批注的文本}// 處理每個批注引用for (var commentRef : sourceRun.getCTR().getCommentReferenceList()) {// 獲取源批注內容var sourceComment = srcDoc.getCommentByID(commentRef.getId().toString());// 在目標文檔創建新批注var targetComment = targetComments.createComment(nextCommentId);// 復制批注內容（關鍵步驟！）targetComment.getCtComment().set(sourceComment.getCtComment().copy());// 設置新IDtargetComment.getCtComment().setId(nextCommentId);// 保存ID映射關系commentIdMap.put(commentRef.getId(), nextCommentId);// ID自增（避免重復）nextCommentId = nextCommentId.add(BigInteger.ONE);}}// 5. 復制段落XML并更新批注IDString xml = sourcePara.getCTP().xmlText();// 替換所有批注ID引用for (var comment : commentIdMap.entrySet()){xml = xml.replaceAll("w:id=\"" + comment.getKey() + "\"", "w:id=\"" + comment.getValue() + "\"");}// 將修改后的XML載入新段落newPara.getCTP().set(CTP.Factory.parse(xml));}}}// 6. 保存合并結果try (FileOutputStream fos = new FileOutputStream(outputPath)) {targetDoc.write(fos);}targetDoc.close();
}

四、關鍵技術點

1. 批注ID重映射機制

• 問題：不同文檔可能有重復的批注ID
• 解決方案：
  • 創建全局計數器 nextCommentId
  • 為每個批注生成新ID
  • 維護commentIdMap映射表

2. XML層級操作

• 直接操作CTP對象：獲取段落底層XML結構
• 正則替換：批量更新批注引用ID

xml = xml.replaceAll("w:id=\"" + oldId + "\"", "w:id=\"" + newId + "\"");

3. 內存管理

• 使用try-with-resources確保資源釋放

try (var srcDoc = new XWPFDocument(new FileInputStream(sourceFile))) {// 處理文檔...
} // 自動關閉流

五、功能擴展建議

1. 支持表格合并：

for (XWPFTable table : srcDoc.getTables()) {// 復制表格到targetDoc
}

2. 處理圖片/圖表：

for (XWPFPictureData picture : srcDoc.getAllPictures()) {// 復制圖片數據
}

3. 保留格式樣式：

newPara.getCTP().setPPr(sourcePara.getCTP().getPPr());

六、注意事項

1. 性能優化：處理大文檔時建議分塊處理
2. ID沖突：必須重新映射批注ID
3. 格式兼容性：
   • 支持wps、office。
   • 支持docx格式
   • 不同Word版本可能有樣式差異
4. 異常處理：實際生產需增加：

   catch (IOException | XmlException e) {// 處理解析異常
   }
   

七、總結

本文實現的合并方案具有以下優勢：

• ? 完美保留批注及引用關系
• ? 避免ID沖突的智能映射
• ? 底層XML操作確保格式兼容
• ? 靈活的擴展性

適用場景：法律文檔合并、論文修訂稿整合、團隊協作文檔匯總等需要保留批注的場景。

技術交流：歡迎在評論區留言討論！

---

附錄：核心依賴說明

依賴包	作用
poi-ooxml	提供XWPFDocument等基礎操作類
poi-ooxml-full	支持完整的OOXML特性解析
xmlbeans	底層XML操作依賴（自動傳遞）

建議在實際使用時注意：

1. 使用POI版本（本文基于5.3.0）
2. 處理10MB+文檔時增加JVM內存：

java -Xmx512m -jar yourApp.jar

此方案已通過以下環境驗證：

• Java 11+
• Apache POI 5.3.0
• Microsoft Word 2016/365