如何使用Apache POI读取、编辑Word文档中图片的altText属性

你在XWPFPictureData中找不到altText相关方法是正常的，既不是你遗漏了API，也不需要强转XWPFPictureData到其他类：XWPFPictureData的职责是存储图片的二进制源数据、资源ID、格式类型这类公共资源信息，而altText（替换文本）是绑定在文档内单个图片引用节点上的属性——同一张图片可以在文档中被多次插入引用，每个引用可以独立设置不同的替换文本，因此altText属性并不在资源类中定义。

Word中图片的altText实际存储在图片挂载节点的非视觉绘图属性段中，对应CTInline（嵌入式图片）、CTAnchor（浮动式图片）两类节点的docPr子节点，其中包含两个和替换文本相关的属性：

• descr：对应Word替换文本面板中的「说明」字段，即常规语义上的alt文本
• title：对应Word替换文本面板中的「标题」字段

操作代码示例 #

读取altText #

import org.openxmlformats.schemas.drawingml.x2006.wordprocessingDrawing.CTAnchor;
import org.openxmlformats.schemas.drawingml.x2006.wordprocessingDrawing.CTInline;
import org.apache.poi.xwpf.usermodel.XWPFPicture;
import org.apache.xmlbeans.XmlObject;
import org.openxmlformats.schemas.drawingml.x2006.main.CTNonVisualDrawingProps;

// 传入从文档段落/ Run 中获取到的XWPFPicture实例
public String[] getPictureAltText(XWPFPicture picture) {
    // 返回值顺序为[替换文本标题, 替换文本说明]
    XmlObject parentNode = picture.getCTPicture().getParent();
    CTNonVisualDrawingProps docPr = null;
    if (parentNode instanceof CTInline inlinePic) {
        docPr = inlinePic.getDocPr();
    } else if (parentNode instanceof CTAnchor anchorPic) {
        docPr = anchorPic.getDocPr();
    }
    if (docPr == null) {
        return new String[]{"", ""};
    }
    return new String[]{docPr.getTitle(), docPr.getDescr()};
}

写入/修改altText #

// 传入目标XWPFPicture实例、要设置的标题、说明文本
public void setPictureAltText(XWPFPicture picture, String title, String descr) {
    XmlObject parentNode = picture.getCTPicture().getParent();
    CTNonVisualDrawingProps docPr = null;
    if (parentNode instanceof CTInline inlinePic) {
        docPr = inlinePic.getDocPr();
    } else if (parentNode instanceof CTAnchor anchorPic) {
        docPr = anchorPic.getDocPr();
    }
    if (docPr != null) {
        docPr.setTitle(title);
        docPr.setDescr(descr);
    }
}

注意：上述代码需要引入Apache POI配套的ooxml-schemas依赖，不同版本POI对应的schemas包版本需要严格匹配，否则会出现类找不到、节点属性读写失败的问题。

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