使用Apache PDFBox嵌入图片被PDF元素遮挡，需置于前景

问题分析 #

你当前使用PDPageContentStream.AppendMode.APPEND模式添加图片，仅能将内容追加到页面原有内容流的末尾，但如果目标PDF包含AcroForm表单字段、注释这类位于内容流上层的元素，图片就会被遮挡。另外，你用JPEGFactory处理PNG图片会导致透明通道丢失，这也是潜在问题。

解决方案 #

1. 使用OVERLAY模式绘制图片（推荐） #

PDFBox 2.0.20及以上版本支持AppendMode.OVERLAY，该模式会创建一个新的内容流，绘制在所有现有内容流和注释之上，确保图片处于最上层。

2. 正确加载PNG图片 #

替换JPEGFactory.createFromImage为PDImageXObject.createFromFile，保留PNG的透明属性。

修改后的完整代码 #

import org.apache.pdfbox.io.MemoryUsageSetting;
import org.apache.pdfbox.pdmodel.PDDocument;
import org.apache.pdfbox.pdmodel.PDPage;
import org.apache.pdfbox.pdmodel.PDPageContentStream;
import org.apache.pdfbox.pdmodel.graphics.image.PDImageXObject;

import java.io.File;

public class ImportImageToPDF {
    public static void main(String[] args) throws Exception {
        PDDocument pdDocument = null;
        try {
            String sourceFilePath = "D:\\files\\sourceFile.pdf";
            String destinationFilePath = "D:\\files\\outputFile.pdf";
            String imagePath = "D:\\files\\image.png";

            // 加载PDF文档
            pdDocument = PDDocument.load(new File(sourceFilePath), MemoryUsageSetting.setupTempFileOnly());
            pdDocument.setAllSecurityToBeRemoved(true);

            PDPage pdPage = pdDocument.getPage(0);

            // 正确加载PNG图片
            PDImageXObject image = PDImageXObject.createFromFile(imagePath, pdDocument);

            // 使用OVERLAY模式创建内容流，确保图片在最上层
            try (PDPageContentStream pageContentStream = new PDPageContentStream(
                    pdDocument, pdPage, PDPageContentStream.AppendMode.OVERLAY, true, true)) {
                pageContentStream.saveGraphicsState();
                // 绘制图片（x=10, y=730, 宽=100, 高=100）
                pageContentStream.drawImage(image, 10, 730, 100, 100);
                pageContentStream.restoreGraphicsState();
            }

            // 保存并关闭文档
            pdDocument.save(new File(destinationFilePath));
        } catch (Exception e) {
            e.printStackTrace();
        } finally {
            if (pdDocument != null) {
                pdDocument.close();
            }
        }
    }
}

低版本PDFBox兼容方案（无OVERLAY模式） #

如果你的PDFBox版本低于2.0.20，可以将图片作为**注释（Annotation）**添加到页面，注释默认位于内容流上层：

// 加载图片后，替换内容流代码为以下部分
PDImageXObject image = PDImageXObject.createFromFile(imagePath, pdDocument);

// 创建图片注释
PDAnnotationRubberStamp stamp = new PDAnnotationRubberStamp();
stamp.setContents("Image Overlay");
stamp.setRectangle(new PDRectangle(10, 730, 100, 100));
PDAppearanceStream appearanceStream = new PDAppearanceStream(pdDocument);
appearanceStream.setResources(new PDResources());
try (PDPageContentStream cs = new PDPageContentStream(pdDocument, appearanceStream)) {
    cs.drawImage(image, 0, 0, 100, 100);
}
stamp.setNormalAppearance(appearanceStream);

// 添加注释到页面
pdPage.getAnnotations().add(stamp);

关键说明 #

• OVERLAY模式直接将内容绘制在所有元素之上，是最简洁的解决方案。
• 加载PNG必须用PDImageXObject.createFromFile，避免JPEGFactory导致的透明丢失和格式错误。
• 仅目标PDF出现遮挡，说明该文档存在上层元素（如表单字段），普通PDF无此类元素所以APPEND模式有效。

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