Apache POI操作Docx文档踩坑指南

文档结构处理问题

使用Apache POI处理Docx文档时，文档结构复杂性可能导致解析异常。XWPFDocument类对嵌套表格、多级列表的支持有限，直接操作段落或表格可能破坏原有样式。

建议通过遍历XWPFParagraph和XWPFRun对象树获取内容，避免直接修改父级节点。处理表格时优先使用XWPFTable.getRow()和XWPFTable.getCell()方法定位元素。

样式丢失问题

直接复制段落或文本时容易丢失字体、颜色等样式属性。XWPFRun对象包含文本样式信息，修改内容时应保持原有run的样式属性：

XWPFRun sourceRun = paragraph.getRuns().get(0);
XWPFRun newRun = paragraph.createRun();
newRun.setText("新内容");
newRun.setFontFamily(sourceRun.getFontFamily());
newRun.setFontSize(sourceRun.getFontSize());

图片处理限制

XWPFPictureData处理嵌入图片时，仅支持EMF、WMF、PICT、JPEG、PNG等格式。插入新图片需通过以下方式：

XWPFRun run = paragraph.createRun();
try (InputStream is = new FileInputStream("image.png")) {
    run.addPicture(is, XWPFDocument.PICTURE_TYPE_PNG, "image.png", Units.toEMU(300), Units.toEMU(200));
}

注意单位转换，Apache POI使用EMU（English Metric Units）作为度量单位。

性能优化建议

处理大文档时可能遇到内存问题。采用事件驱动的解析模式可降低内存消耗：

OPCPackage pkg = OPCPackage.open(largeFile);
XWPFDocument doc = new XWPFDocument(pkg);
for (XWPFParagraph p : doc.getParagraphs()) {
    // 逐段处理
}
pkg.close();

对于批量操作，考虑使用SAX解析器或拆分文档处理。

版本兼容性问题

不同Office版本生成的Docx可能存在兼容性问题。建议在代码中添加版本检测：

XWPFDocument doc = new XWPFDocument(input);
String appVersion = doc.getProperties().getExtendedProperties().getUnderlyingProperties().getApplication();

处理文档前进行标准化预处理，如通过Office软件另存为统一格式。

特殊字符处理

Docx使用XML格式存储内容，特殊字符如"<"、">"需要转义。建议使用工具类处理文本内容：

String safeText = org.apache.poi.util.StringUtil.xmlEncode(rawText);
run.setText(safeText);

文档保护与加密

加密文档需先解密才能处理。若文档受密码保护，需使用其他库先行解密：

POIFSFileSystem fs = new POIFSFileSystem(encryptedFile);
EncryptionInfo info = new EncryptionInfo(fs);
Decryptor decryptor = Decryptor.getInstance(info);
if (decryptor.verifyPassword(password)) {
    InputStream decryptedStream = decryptor.getDataStream(fs);
    XWPFDocument doc = new XWPFDocument(decryptedStream);
}

批注与修订处理

文档批注存储在XWPFComments对象中，需单独处理：

XWPFCommentsMetadataExtractor comments = doc.getComments();
for (XWPFComment comment : comments.getComments()) {
    String author = comment.getAuthor();
    String text = comment.getText();
}

处理修订内容时需检查XWPFFooter、XWPFHeader等部分的修订记录。

字段更新问题

文档中的动态字段（如页码、目录）不会自动更新。需要手动触发更新：

CTSectPr sectPr = doc.getDocument().getBody().getSectPr();
if (sectPr != null) {
    sectPr.addNewPgNumType().setStart(1);
}

处理后建议通过Word应用程序强制刷新字段。