PDF 表单字段属性详解

🔑 主要字段类型标识符 /FT (Field Type)

/FT 定义了 PDF 表单字段的核心类型，决定了字段的基本行为。以下是常见的字段类型及其用途：

• /Tx (Text Field, 文本字段)

  • 用于输入单行或多行文本、数字、日期等。
  • 典型应用：姓名、地址、电话号码、备注等。
  • 支持属性：单行、多行、密码输入、最大字符数限制等。

• /Btn (Button Field, 按钮字段)

  • 包括复选框 (Checkbox)、单选按钮 (Radio Button) 和推送按钮 (Push Button)。
  • 通过 /Ff 标志位区分具体子类型。
  • 典型应用：选择"是/否"、选项组、触发动作。

• /Ch (Choice Field, 选择字段)

  • 包括下拉选择框 (Combo Box) 和列表框 (List Box)。
  • 通过 /Ff 标志位区分具体行为（例如是否可编辑）。
  • 典型应用：国家选择、等级评分、产品类别。

• /Sig (Signature Field, 签名字段)

  • 用于数字签名或手写签名。
  • 典型应用：合同签署、认证文档。

---

🎛️ 字段标志位 /Ff (Field Flags)

/Ff 是一个位掩码，通过二进制位组合定义字段的具体行为。每个字段类型（/Tx、/Btn、/Ch）有特定的标志位支持。以下是常见标志位的详细说明：

对于按钮字段 (/Btn)

• Bit 15 (Pushbutton, 推送按钮) : 值为 1 << 14 (16384)。表示字段是推送按钮，用于触发动作（如提交表单）。
• Bit 16 (Radio, 单选按钮) : 值为 1 << 15 (32768)。表示字段是单选按钮，同一组内只能选择一个选项。
• Bit 17 (NoToggleToOff) : 值为 1 << 16 (65536)。仅对单选按钮有效，禁止取消选择（即必须选中一个选项）。
• 示例 ：/Ff 32768 表示这是一个单选按钮字段。

对于选择字段 (/Ch)

• Bit 18 (Combo, 下拉选择框) : 值为 1 << 17 (131072)。表示字段是下拉选择框，允许用户从预定义选项中选择或输入自定义值（若允许编辑）。
• Bit 19 (Edit) : 值为 1 << 18 (262144)。表示下拉选择框支持用户输入自定义值。
• Bit 20 (Sort) : 值为 1 << 19 (524288)。表示选项列表按字母顺序排序。
• 示例 ：/Ff 131072 表示这是一个下拉选择框。

对于文本字段 (/Tx)

• Bit 13 (Multiline) : 值为 1 << 12 (4096)。表示字段支持多行文本输入。
• Bit 14 (Password) : 值为 1 << 13 (8192)。表示字段为密码输入，内容显示为掩码（如 ****）。
• Bit 21 (FileSelect) : 值为 1 << 20 (1048576)。表示字段用于选择文件路径。
• Bit 23 (MaxLen) : 配合 /MaxLen 属性，限制文本字段的最大字符数。
• 示例 ：/Ff 4096 表示这是一个多行文本字段。

---

📝 其他重要属性

以下是 PDF 表单字段的常见属性，适用于所有字段类型：

• /T (Field Name): 字段的唯一名称，用于标识字段。

  • 格式：字符串（如 "FirstName" 或 "CountryComboBox"）。
  • 用途：程序化访问字段或在表单提交时标识数据。
  • 注意：名称应唯一，避免特殊字符以确保兼容性。

• /V (Field Value): 字段的当前值。

  • 对于 /Tx：字符串（如 "John Doe"）。
  • 对于 /Btn："Yes"、"Off"（复选框/单选按钮）或动作相关值。
  • 对于 /Ch：选中的选项值（如 "Austria"）或用户输入的自定义值。
  • 对于 /Sig：签名数据或空值。

• /Opt (Options) : 选择字段 (/Ch) 的选项列表。

  • 格式：数组，如 ["Austria", "Belgium", "Canada"]。
  • 用途：定义下拉框或列表框的可选值。
  • 注意：选项顺序影响显示，值区分大小写。

• /Rect (Rectangle): 字段在页面上的位置和大小。

  • 格式：[x1, y1, x2, y2]，表示左下角 (x1, y1) 和右上角 (x2, y2) 的坐标（单位：PDF 点，1 点 = 1/72 英寸）。
  • 用途：定义字段的显示区域。
  • 示例：[165.7, 315.9, 315.7, 330.1] 表示一个矩形区域。

• /DA (Default Appearance): 定义字段的默认外观（如字体、大小、颜色）。

  • 格式：字符串，如 "/Helvetica 12 Tf 0 0 0 rg"（表示 Helvetica 字体，12 点，黑色）。
  • 用途：控制文本字段的显示样式。

• /AP (Appearance Streams): 定义字段的视觉外观（正常、鼠标悬停、选中等状态）。

  • 用途：自定义字段的外观（如复选框的勾选图标）。

---

🛠️ 在代码中的应用

以下是一个 Python 示例，展示如何使用 PyPDF2 或 pdfplumber 等库操作 PDF 表单字段属性（假设使用 PyPDF2）：

from PyPDF2 import PdfReader, PdfWriter
from PyPDF2.generic import NameObject, ArrayObject, NumberObject, TextStringObject

# 读取 PDF 文件
reader = PdfReader("form.pdf")
writer = PdfWriter()

# 获取表单字段
form = reader.get_form_text_fields()

# 示例：添加一个下拉选择框字段
new_field = {
    "/FT": NameObject("/Ch"),  # 选择字段
    "/T": TextStringObject("CountryComboBox"),  # 字段名称
    "/Ff": NumberObject(131072),  # 下拉选择框标志位
    "/V": TextStringObject("Austria"),  # 默认值
    "/Opt": ArrayObject([TextStringObject("Austria"), TextStringObject("Belgium"), TextStringObject("Canada")]),  # 选项列表
    "/Rect": ArrayObject([NumberObject(165.7), NumberObject(315.9), NumberObject(315.7), NumberObject(330.1)]),  # 位置
    "/DA": TextStringObject("/Helvetica 12 Tf 0 0 0 rg"),  # 默认外观
}

# 将字段添加到 PDF
page = reader.pages[0]
if "/Annots" not in page:
    page[NameObject("/Annots")] = ArrayObject()
page["/Annots"].append(new_field)

# 保存修改后的 PDF
writer.add_page(page)
with open("modified_form.pdf", "wb") as output:
    writer.write(output)

说明：

• 上述代码创建了一个下拉选择框字段，包含国家选项。
• /Ff 设置为 131072 表示这是一个下拉选择框。
• /Rect 定义了字段在页面上的位置。
• 实际操作时，需确保坐标和页面尺寸匹配。

---

📈 实际示例

以下是一个实际 PDF 表单字段的属性示例（基于您提供的部分内容）：

/FT: /Ch
/Ff: 131072
/T: "CountryComboBox"
/V: "Austria"
/Opt: ["Austria", "Belgium", "Canada", "Denmark"]
/Rect: [165.7, 315.9, 315.7, 330.1]
/DA: "/Helvetica 12 Tf 0 0 0 rg"

解析：

• 类型 ：选择字段 (/Ch)，下拉选择框（由 /Ff 131072 确定）。
• 名称 ："CountryComboBox"，唯一标识字段。
• 值 ："Austria"，当前选中的选项。
• 选项：包含四个国家选项，用户可从中选择。
• 位置 ：字段位于页面坐标 [165.7, 315.9, 315.7, 330.1]。
• 外观：使用 Helvetica 字体，12 点，黑色。

---