如何用PDFBox为PDF表单域附加图片且不使已有数字签名失效？

• 开发需求：需在不使PDF中已有数字签名失效的前提下，为指定表单域附加图片，计划通过PDFBox实现该功能。
• 当前实现：因PDF无原生图片表单域，采用PDPushButton作为替代方案，但先签署签名域再向按钮域填充图片时，会导致原有签名失效。
• 现有填充图片代码：

@SneakyThrows
public static void fillInitialField(String inputFilePath, String outputFilePath) {
    // Load input file
    PDDocument document = PDDocument.load(new File(inputFilePath));

    // Find and link the relevant signature field
    PDPushButton initial = PdfService.findInitial(document, "132323423180965");

    PDImageXObject pdImageXObject = PDImageXObject.createFromFile("initial.png", document);
    float width = 10 * pdImageXObject.getWidth();
    float height = 10 * pdImageXObject.getHeight();

    PDAppearanceStream pdAppearanceStream = new PDAppearanceStream(document);
    pdAppearanceStream.setResources(new PDResources());
    try (PDPageContentStream pdPageContentStream = new PDPageContentStream(document, pdAppearanceStream)) {
        pdPageContentStream.drawImage(pdImageXObject, 200, 300, width, height);
    }
    pdAppearanceStream.setBBox(new PDRectangle(width, height));

    List<PDAnnotationWidget> widgets = initial.getWidgets();
    for (PDAnnotationWidget pdAnnotationWidget : widgets) {

        PDAppearanceDictionary pdAppearanceDictionary = pdAnnotationWidget.getAppearance();
        if (pdAppearanceDictionary == null) {
            pdAppearanceDictionary = new PDAppearanceDictionary();
            pdAnnotationWidget.setAppearance(pdAppearanceDictionary);
        }

        pdAppearanceDictionary.setNormalAppearance(pdAppearanceStream);
    }
    initial.setReadOnly(true);

    // Save and close the document
    FileOutputStream fos = new FileOutputStream(outputFilePath);
    document.save(fos);
    document.close();
}

要实现不破坏签名的图片填充，核心是采用PDF增量更新模式——该模式会将修改内容追加到文件末尾，而非覆盖原始内容，从而保留签名对应的原始文档哈希值，确保签名有效性。

修改后的代码实现 #

@SneakyThrows
public static void fillInitialField(String inputFilePath, String outputFilePath) {
    // 以增量更新模式加载文档，保留原有安全配置
    try (PDDocument document = PDDocument.load(new File(inputFilePath))) {
        document.setAllSecurityToBeRemoved(false);
        
        // 找到目标PDPushButton域
        PDPushButton initial = PdfService.findInitial(document, "132323423180965");

        PDImageXObject pdImageXObject = PDImageXObject.createFromFile("initial.png", document);
        float width = 10 * pdImageXObject.getWidth();
        float height = 10 * pdImageXObject.getHeight();

        PDAppearanceStream pdAppearanceStream = new PDAppearanceStream(document);
        pdAppearanceStream.setResources(new PDResources());
        try (PDPageContentStream pdPageContentStream = new PDPageContentStream(document, pdAppearanceStream)) {
            pdPageContentStream.drawImage(pdImageXObject, 200, 300, width, height);
        }
        pdAppearanceStream.setBBox(new PDRectangle(width, height));

        List<PDAnnotationWidget> widgets = initial.getWidgets();
        for (PDAnnotationWidget pdAnnotationWidget : widgets) {
            PDAppearanceDictionary pdAppearanceDictionary = pdAnnotationWidget.getAppearance();
            if (pdAppearanceDictionary == null) {
                pdAppearanceDictionary = new PDAppearanceDictionary();
                pdAnnotationWidget.setAppearance(pdAppearanceDictionary);
            }
            pdAppearanceDictionary.setNormalAppearance(pdAppearanceStream);
        }
        initial.setReadOnly(true);

        // 使用增量更新保存文档，避免覆盖原始内容
        try (FileOutputStream fos = new FileOutputStream(outputFilePath)) {
            document.saveIncremental(fos);
        }
    }
}

关键修改说明 #

1. 替换保存方式：用document.saveIncremental()替代原有的document.save()，这是实现增量更新的核心，确保修改内容追加到文件末尾。
2. 保留安全配置：加载文档时设置setAllSecurityToBeRemoved(false)，避免移除签名相关的安全属性。
3. 限定修改范围：仅修改按钮的外观流，不改动PDF的核心结构（如页面内容、表单域定义），确保签名保护的内容不受影响。

额外注意事项 #

• 用于填充图片的PDPushButton域必须在签名前就已存在于PDF中，签名后新增表单域会破坏签名有效性。
• 若需批量处理，需确保每个文档的增量更新操作独立完成，避免跨文档的资源冲突。

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