已签PAdES文档添加图片不失效原签名的技术咨询

1. 能否在文本字段中添加图片（如二维码）？ #

不行。DocMDP Level 2 仅允许修改表单字段的**值（/V）**及相关表单填写操作，直接修改文本字段的部件注释（如添加图片）会涉及修改字段的外观字典（/AP）或注释内容，这超出了Level 2的权限范围，必然导致初始签名失效。

如果需要添加二维码这类图片内容，应使用按钮字段（Pushbutton）。按钮字段的外观配置属于表单填写的允许操作范畴，修改其外观或关联图片流不会破坏原有签名。

2. 除/V外，还有哪些AcroForm字段字典值可修改？ #

根据PDF规范（ISO 32000-1），DocMDP Level 2权限允许修改以下与表单填写直接相关的字段条目：

• /DV：字段默认值，修改后不影响原有签名
• /AS：字段外观状态，适用于按钮、复选框等有状态的字段，切换状态外观属于允许操作
• /Ff：字段标志，仅可修改不改变字段核心类型的标志（如设置必填、只读，不能将文本字段改为按钮字段）
• 对于按钮字段，/AP字典下的状态流（如/N正常状态、/R按下状态）可修改，用于配置按钮外观

3. 能否向/V字段传入流数据？ #

文本字段的/V仅支持字符串类型，无法直接传入流数据，强行传入会违反PDF规范并导致签名失效。

若要存储图片数据，需使用按钮字段：按钮字段的/V可设置为状态名称（如:Off），并通过/AP字典关联图片流（XObject），以此实现图片显示的需求。

HexaPDF代码失效的解决方法 #

之前的代码失效大概率是因为未采用增量更新、字段类型错误或外观配置不当。以下是可正常运行的示例代码，用于在已签名的DocMDP Level 2文档中添加/修改按钮字段的二维码：

require 'hexapdf'

# 打开已签名文档
doc = HexaPDF::Document.open('signed_input.pdf')

# 获取或初始化AcroForm（已签名文档通常已有AcroForm）
acro_form = doc.acro_form || doc.add({Type: :AcroForm, Fields: []})

# 查找目标按钮字段，不存在则创建
button_field = acro_form.fields.find { |f| f[:T] == 'QR_Code_Field' } || begin
  # 创建按钮部件注释
  widget = doc.add({
    Type: :Annot,
    Subtype: :Widget,
    FT: :Btn,          # 指定为按钮字段
    T: 'QR_Code_Field',# 字段名称
    Rect: [150, 250, 300, 400], # 字段位置（左下x, 左下y, 右上x, 右上y）
    Ff: 1 << 15,       # 设置按钮为无状态（仅显示固定外观）
    AP: {}             # 初始化外观字典
  })
  acro_form[:Fields] << widget
  widget
end

# 加载二维码图片（支持PNG/JPG等格式）
qr_xobject = doc.images.add('qrcode.png').xobject

# 配置按钮的正常状态外观
button_field[:AP][:N] = qr_xobject

# 增量保存文档（关键：避免覆盖原有签名）
doc.write('updated_output.pdf', incremental: true)

代码说明： #

• 必须使用incremental: true参数保存，增量更新不会破坏原有签名的哈希值
• 字段类型必须设置为FT: :Btn（按钮），而非文本字段的FT: :Tx
• 通过/AP字典关联图片XObject，而非修改文本字段的注释内容

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