Apache PDFBox 3.0.3：已勾选复选框发送后变为未勾选求助

针对你遇到的PDF模板复选框chkbox1调用check()后仍未勾选的问题，可按以下步骤排查修复：

1. 确保修改后保存并关闭文档 #

你的代码中缺少保存PDF文档的关键步骤，修改字段后必须将变更写入输出流并关闭文档，否则所有修改不会生效。

2. 强制设置AcroForm的NeedAppearances为false #

部分PDF模板的NeedAppearances属性设为true，会导致PDF阅读器自动重新生成表单外观，覆盖你设置的复选框状态。需手动将其设为false，让PDFBox生成正确的外观。

3. 匹配复选框的实际导出值 #

部分自定义模板的复选框勾选状态对应的导出值不是默认的Yes，直接调用check()可能不匹配模板定义。建议获取复选框的实际勾选值后再设置。

修改后的完整代码 #

fun generatePdf(outputStream: OutputStream) {
    val pdf = this::class.java.classLoader.getResourceAsStream("pdf/role.pdf")
        ?: throw FileNotFoundException("PDF template not found at pdf/role.pdf")
    PDDocument.load(pdf.readAllBytes()).use { pdfTemplate ->
        this.populateTemplateFields(pdfTemplate, "newMail")
        // 保存修改后的PDF到输出流
        pdfTemplate.save(outputStream)
    }
}

private fun populateTemplateFields(
    pdfTemplate: PDDocument,
    newMail: String,
) {
    val acroForm = pdfTemplate.documentCatalog.acroForm ?: return

    // 设置NeedAppearances为false，避免阅读器重置外观
    acroForm.isNeedAppearances = false

    val checkbox = acroForm.getField("chkbox1") as PDCheckBox
    // 获取复选框的实际勾选导出值，再设置状态
    val onValue = checkbox.onValue
    checkbox.setValue(onValue)

    acroForm.getField("new_mail")?.setValue(newMail)
}

额外验证步骤 #

• 打开PDF模板，用PDF编辑工具查看chkbox1的属性，确认其勾选状态对应的导出值是否与代码中获取的onValue一致。
• 确保处理后的PDF在邮件中是以附件形式发送原始PDF文件，而非转换为图片或其他格式，避免表单字段丢失。

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