使用Apache POI为已有PPT幻灯片设置背景图时打开报错

尝试为已存在的、带有空白背景且包含文本和图片组件的特定幻灯片设置图片背景，使用Apache POI生成PPT后打开报错。

原代码 #

XMLSlideShow slideShow = new XMLSlideShow(new FileInputStream("test.pptx"));
byte[] picData = IOUtils.toByteArray(new FileInputStream("image.jpg"));
XSLFPictureData pcData = slideShow.getSlides().get(0).getSlideShow().addPicture(picData, PictureData.PictureType.JPEG);
CTBackgroundProperties backgroundProperties = slideShow.getSlides().get(0).getXmlObject().getCSld().addNewBg().addNewBgPr();
CTBlipFillProperties blipFillProperties = backgroundProperties.addNewBlipFill();
CTRelativeRect ctRelativeRect = blipFillProperties.addNewStretch().addNewFillRect();
String idx = slideShow.getSlides().get(0).addRelation(null, XSLFRelation.IMAGES, pcData).getRelationship().getId();
CTBlip blib = blipFillProperties.addNewBlip();
blib.setEmbed(idx);

try (FileOutputStream fileOut = new FileOutputStream("test.pptx")) {
    slideShow.write(fileOut);
}

原代码存在多个导致PPT打开报错的问题，以下是修复后的代码及说明：

修复后代码 #

import org.apache.poi.sl.usermodel.PictureData;
import org.apache.poi.xslf.usermodel.*;
import org.openxmlformats.schemas.presentationml.x2006.main.*;
import org.apache.commons.io.IOUtils;

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

public class SlideBackgroundFix {
    public static void main(String[] args) throws IOException {
        XMLSlideShow slideShow = new XMLSlideShow(new FileInputStream("test.pptx"));
        XSLFSlide slide = slideShow.getSlides().get(0);
        byte[] picData = IOUtils.toByteArray(new FileInputStream("image.jpg"));
        XSLFPictureData pcData = slideShow.addPicture(picData, PictureData.PictureType.JPEG);

        CTSlide slideXml = slide.getXmlObject();

        // 获取或创建幻灯片背景节点，避免重复创建
        CTBackground bg = slideXml.getCSld().getBg();
        if (bg == null) {
            bg = slideXml.getCSld().addNewBg();
        }

        // 获取或创建背景属性
        CTBackgroundProperties bgPr = bg.getBgPr();
        if (bgPr == null) {
            bgPr = bg.addNewBgPr();
        }

        // 清理已有填充类型，防止冲突
        if (bgPr.isSetBlipFill()) {
            bgPr.unsetBlipFill();
        }
        if (bgPr.isSetSolidFill()) {
            bgPr.unsetSolidFill();
        }

        // 添加图片填充配置
        CTBlipFillProperties blipFill = bgPr.addNewBlipFill();
        CTBlip blip = blipFill.addNewBlip();
        // 关联图片关系ID，自动处理命名空间
        blip.setEmbed(slide.addRelation(null, XSLFRelation.IMAGES, pcData).getRelationship().getId());

        // 设置图片拉伸铺满背景
        CTStretch stretch = blipFill.addNewStretch();
        stretch.addNewFillRect();

        // 移除背景继承，确保使用当前幻灯片的自定义背景
        if (bg.isSetBgRef()) {
            bg.unsetBgRef();
        }

        try (FileOutputStream fileOut = new FileOutputStream("test_fixed.pptx")) {
            slideShow.write(fileOut);
        }
    }
}

关键修复点 #

• 复用已有背景节点：原代码直接addNewBg()会强制创建新的背景节点，导致XML结构冲突，改为先检查节点是否存在，不存在再创建。
• 清理冲突填充：移除幻灯片原有的纯色填充或其他背景填充，避免多种填充类型共存导致PPT解析错误。
• 正确关联图片关系：通过幻灯片实例调用addRelation，确保图片关系正确绑定到当前幻灯片，同时Apache POI会自动处理r:embed的命名空间，避免属性无法识别。
• 移除背景继承：取消从母版或布局继承背景的设置，确保自定义背景生效。

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