Apache POI复制XWPFDocument段落异常及文档损坏问题咨询

问题背景 #

我尝试用Apache POI复制XWPFDocument中的段落，但POI没有直接在任意位置插入预制段落的方法，只能先通过insertNewParagraph()插入临时段落，再用setParagraph()替换成目标段落。但insertNewParagraph()需要传入XmlCursor，没法直接指定元素索引，操作起来很麻烦。

我用包含6个段落A、B、C、D、E、F的TestIn.docx做测试，调试发现：

• 替换首个临时段落后，元素列表里还留着临时段落，但段落列表已经更新成克隆后的段落；
• 插入第二个临时段落后，元素列表的位置是对的，但段落列表里这个临时段列出现在了头部。
  最终保存的Word文档显示正常，但这两个列表的状态不一致。

当文档包含表格时，doc.getPosOfParagraph()返回的是包含表格的元素列表索引，而setParagraph()需要的是排除表格的段落列表索引。doc.getParagraphPos()因为临时段落位置异常返回错误值，我只能通过遍历元素列表统计段落数来规避，但还是存在列表不一致的问题。

实际项目里用这个方法时，Word会提示文档损坏，但修复后内容显示正常。

咨询问题 #

1. 有没有更优的方法解决临时段落替换后列表不一致、第二个临时段列出现在头部的问题？比如复用XmlCursor、批量生成临时段落再统一替换是否可行？
2. 为什么实际项目中会出现文档损坏提示，该怎么解决？

测试代码 #

import java.io.FileInputStream;
import java.io.FileOutputStream;

import org.apache.poi.xwpf.usermodel.IBodyElement;
import org.apache.poi.xwpf.usermodel.XWPFDocument;
import org.apache.poi.xwpf.usermodel.XWPFParagraph;
import org.apache.xmlbeans.XmlCursor;
import org.openxmlformats.schemas.wordprocessingml.x2006.main.CTP;

public class ParagraphIssue
{
    public void debugElement (IBodyElement elem, StringBuilder s, XWPFParagraph a, XWPFParagraph b, XWPFParagraph c, XWPFParagraph d, XWPFParagraph e, XWPFParagraph f,
        XWPFParagraph t1, XWPFParagraph r1, XWPFParagraph t2, XWPFParagraph r2)
    {
        if (s.length () > 0) s.append (" ");
        if (elem == a) s.append ("A");
        else if (elem == b) s.append ("B");
        else if (elem == c) s.append ("C");
        else if (elem == d) s.append ("D");
        else if (elem == e) s.append ("E");
        else if (elem == f) s.append ("F");
        else if (elem == t1) s.append ("T1");
        else if (elem == r1) s.append ("R1");
        else if (elem == t2) s.append ("T2");
        else if (elem == r2) s.append ("R2");
        else s.append ("U");
    }
    
    public void debug (XWPFDocument doc, XWPFParagraph a, XWPFParagraph b, XWPFParagraph c, XWPFParagraph d, XWPFParagraph e, XWPFParagraph f,
        XWPFParagraph t1, XWPFParagraph r1, XWPFParagraph t2, XWPFParagraph r2)
    {
        StringBuilder s = new StringBuilder ();
        for (IBodyElement elem : doc.getBodyElements ())
            debugElement (elem, s, a, b, c, d, e, f, t1, r1, t2, r2);
        System.out.println("Elements: " + s);
        
        s = new StringBuilder ();
        for (XWPFParagraph para : doc.getParagraphs ())
            debugElement (para, s, a, b, c, d, e, f, t1, r1, t2, r2);
        System.out.println("Paragraphs: " + s);
    }
    
    public void run (XWPFDocument doc, int insertionPoint)
    {
        XWPFParagraph paraA = doc.getParagraphs().get(0);
        XWPFParagraph paraB = doc.getParagraphs().get(1);
        XWPFParagraph paraC = doc.getParagraphs().get(2);
        XWPFParagraph paraD = doc.getParagraphs().get(3);
        XWPFParagraph paraE = doc.getParagraphs().get(4);
        XWPFParagraph paraF = doc.getParagraphs().get(5);
        
        System.out.println ("--- Document initial state ---");
        debug (doc, paraA, paraB, paraC, paraD, paraE, paraF, null, null, null, null);

        // Clone the first paragraph
        XWPFParagraph cloneThis = (XWPFParagraph) doc.getBodyElements ().get (0);
        XWPFParagraph clonedPara = new XWPFParagraph ((CTP) cloneThis.getCTP ().copy (), doc);
        
        // Add new paragraph before the final paragraph
        XWPFParagraph insertBeforePara = (XWPFParagraph) doc.getBodyElements ().get (insertionPoint);
        XmlCursor cursor = insertBeforePara.getCTP ().newCursor ();
        
        XWPFParagraph newPara = doc.insertNewParagraph (cursor);
        newPara.insertNewRun (0).setText ("this should get replaced");
        
        System.out.println ("--- Insert 1st temporary para before F ---");
        debug (doc, paraA, paraB, paraC, paraD, paraE, paraF, newPara, clonedPara, null, null);
        
        int newParaIndex = 0;
        for (IBodyElement elem : doc.getBodyElements ())
        {
            if (elem == newPara)
                break;
            else if (elem.getElementType () == newPara.getElementType ())
                newParaIndex++;
        }
        
        System.out.println ("1st temporary para is at index " + newParaIndex);      // 5, as expected
        
        // Now replace the added paragraph with the cloned one
        doc.setParagraph (clonedPara, newParaIndex);
        System.out.println ("--- Replace 1st temporary para ---");
        debug (doc, paraA, paraB, paraC, paraD, paraE, paraF, newPara, clonedPara, null, null);
        
        // Do exactly the same thing again to clone the second paragraph
        XWPFParagraph cloneThis2 = (XWPFParagraph) doc.getBodyElements ().get (1);
        XWPFParagraph clonedPara2 = new XWPFParagraph ((CTP) cloneThis2.getCTP ().copy (), doc);
        
        XWPFParagraph insertBeforePara2 = (XWPFParagraph) doc.getBodyElements ().get (insertionPoint + 1);
        XmlCursor cursor2 = insertBeforePara2.getCTP ().newCursor ();
        
        XWPFParagraph newPara2 = doc.insertNewParagraph (cursor2);
        newPara2.insertNewRun (0).setText ("this should get replaced too");

        System.out.println ("--- Insert 2nd temporary para before F ---");
        debug (doc, paraA, paraB, paraC, paraD, paraE, paraF, newPara, clonedPara, newPara2, clonedPara2);
        
        int newParaIndex2 = 0;
        for (IBodyElement elem : doc.getBodyElements ())
        {
            if (elem == newPara2)
                break;
            else if (elem.getElementType () == newPara2.getElementType ())
                newParaIndex2++;
        }
        
        System.out.println ("2nd temporary para is at index " + newParaIndex2);
        
        doc.setParagraph (clonedPara2, newParaIndex2);      // So then this replaces the wrong paragraph
        System.out.println ("--- Replace 2nd temporary para ---");
        debug (doc, paraA, paraB, paraC, paraD, paraE, paraF, newPara, clonedPara, newPara2, clonedPara2);
    }
    
    public final static void main (final String [] args)
    {
        try (FileInputStream in = new FileInputStream ("W:\\TestIn.docx"))
        {
            XWPFDocument doc = new XWPFDocument (in);
            new ParagraphIssue ().run (doc, 5);
            
            try (FileOutputStream out = new FileOutputStream ("W:\\TestOut.docx"))
            {
                doc.write (out);
            }
        }
        catch (Exception e)
        {
            e.printStackTrace ();
        }
    }
}

解决方案 #

问题1：列表不一致与临时段落位置异常的解决方法 #

核心问题是Apache POI的XWPFDocument内部维护了两个独立列表：bodyElements（包含所有文档元素，如段落、表格）和paragraphs（仅包含段落），setParagraph()只更新了paragraphs列表，未同步更新bodyElements，导致两者状态不一致；第二个临时段列出现在头部是因为插入后paragraphs列表的索引计算逻辑出错。

更优的实现方式是直接操作底层XML结构，跳过临时段落步骤，直接将克隆的段落XML插入目标位置，避免列表不同步问题：

1. 克隆段落的CTP对象：

XWPFParagraph sourcePara = doc.getParagraphs().get(sourceIndex);
CTP clonedCTP = (CTP) sourcePara.getCTP().copy();

2. 获取目标位置的段落CTP，用XmlCursor插入克隆的CTP：

XWPFParagraph targetPara = doc.getParagraphs().get(targetIndex);
XmlCursor cursor = targetPara.getCTP().newCursor();
// 移动到目标段落之前的位置
cursor.moveXml(targetPara.getCTP());
cursor.insertBefore(clonedCTP);
cursor.dispose();

3. 手动刷新POI内部段落列表：

doc.getParagraphs().clear();
for (IBodyElement elem : doc.getBodyElements()) {
    if (elem instanceof XWPFParagraph) {
        doc.getParagraphs().add((XWPFParagraph) elem);
    }
}

复用XmlCursor或批量生成临时段落再统一替换的方案无法从根本上解决列表不同步问题，因为只要使用setParagraph()就会导致两个列表状态不一致。

问题2：文档损坏提示的解决方法 #

Word提示文档损坏通常是因为生成的OOXML结构不符合规范，常见原因及解决方法：

1. 重复段落ID：克隆CTP时，POI不会自动修改段落的pPr/pId属性，导致多个段落ID重复，触发Word损坏检测。解决方法是手动生成唯一pId：

int nextId = doc.getMaxParagraphId() + 1;
clonedCTP.getPPr().setPId(CTP.PPR.PId.Factory.newInstance(nextId));
doc.setMaxParagraphId(nextId);

2. 未处理关联元素：段落中的脚注、样式引用等克隆时需确保引用ID在文档中存在，可通过XWPFParagraph.getStyleID()等方法同步样式。
3. XmlCursor未释放：使用XmlCursor后必须调用cursor.dispose()，避免残留无效XML节点。
4. POI版本问题：旧版本XWPF模块存在OOXML结构bug，建议升级到最新稳定版本（如5.2.3及以上）。

另外，测试代码中文件路径需转义反斜杠（"W:\\TestIn.docx"），否则会导致路径解析错误，间接引发文档损坏。

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