PDF 表单填充器

以编程方式向 PDF 表单中填入文本值和复选框状态。使用 pdfrw 设置表单字段值，同时保留外观流（appearance streams），确保 PDF 查看器能正确渲染。

快速开始

使用一个包含字段名与对应值的字典来填充 PDF 表单：

from pdf_form_filler import fill_pdf_form

fill_pdf_form(
    input_pdf="form.pdf",
    output_pdf="form_filled.pdf",
    data={
        "Name": "John Doe",
        "Email": "john@example.com",
        "Herr": True,  # 复选框
        "Dienstreise": True,
    }
)

特性

• 文本字段：可设置任意文本值（姓名、日期、地址等）
• 复选框：支持布尔值（True 表示勾选，False 或 None 表示未勾选）
• 外观状态：正确设置 /On 和 /Off 状态，以保障 PDF 查看器正常渲染
• 保留结构完整性：不剥离表单功能，填充后的 PDF 仍可进一步编辑
• 无额外依赖：仅依赖 pdfrw（轻量级、纯 Python 实现）

工作原理

1. 打开 PDF 模板文件
2. 遍历所有表单字段
3. 对匹配字段名的字段设置对应值
4. 针对复选框，同时设置 /V（字段值）和 /AS（外观状态）
5. 保存已填充的 PDF 文件

字段名匹配规则

字段名必须与 PDF 表单中定义的名称完全一致。常见命名模式如下：

• 德语表单：Herr、Frau、Dienstreise、Geschäftsnummer LfF
• 英语表单：Full Name、Email、Agree、Submit
• 日期字段：Date、DOB、Start Date

如需探查 PDF 中的具体字段名，可使用 list_pdf_fields()：

from pdf_form_filler import list_pdf_fields

fields = list_pdf_fields("form.pdf")
for field_name, field_type in fields:
    print(f"{field_name}: {field_type}")

字段类型说明：

• text：文本输入字段
• checkbox：布尔型复选框
• radio：单选按钮
• dropdown：下拉选择框
• signature：签名字段

示例：职位申请表单

fill_pdf_form(
    input_pdf="job_application.pdf",
    output_pdf="job_application_filled.pdf",
    data={
        "Full Name": "Jane Smith",
        "Email": "jane.smith@example.com",
        "Phone": "555-1234",
        "Position": "Software Engineer",
        "Years Experience": "5",
        
        # 复选框
        "Willing to relocate": True,
        "Available immediately": False,
        "Background check consent": True,
    }
)

高级用法

部分填充

仅填充指定字段，其余字段保持空白：

data = {"Name": "Jane Doe"}  # 仅设置 Name 字段
fill_pdf_form("form.pdf", "form_filled.pdf", data)

动态字段探测

获取全部字段并交互式提示用户输入值：

from pdf_form_filler import list_pdf_fields

fields = list_pdf_fields("form.pdf")
data = {}
for field_name, field_type in fields:
    if field_type == "text":
        data[field_name] = input(f"请输入 {field_name}: ")
    elif field_type == "checkbox":
        data[field_name] = input(f"是否勾选 {field_name}? (y/n): ").lower() == 'y'

fill_pdf_form("form.pdf", "form_filled.pdf", data)

批量填充

使用相同数据批量填充多个 PDF 文件：

import os
from pdf_form_filler import fill_pdf_form

data = {"Name": "John Doe", "Date": "2026-01-24"}

for filename in os.listdir("forms/"):
    if filename.endswith(".pdf"):
        fill_pdf_form(
            f"forms/{filename}",
            f"forms_filled/{filename}",
            data
        )

故障排查

复选框未显示视觉效果

部分 PDF 查看器不会立即渲染复选框。虽然字段值已正确设置（/On 或 /Off），但外观并未自动更新。建议尝试以下查看器：

• Adobe Reader（将自动渲染）
• Firefox（对表单支持更佳）
• Linux 下的 evince 或 okular（通常可正常工作）

未找到字段名

请使用 list_pdf_fields() 确认字段名是否准确。PDF 表单字段命名可能存在以下情况：

• 使用非描述性名称（例如 Field_1 而非语义化名称）
• 存在嵌套字段结构

文本被截断

某些 PDF 的文本字段宽度较窄，可能导致内容显示不全。解决方案包括：

1. 使用更短的输入值
2. 在原始 PDF 模板中减小字体大小
3. 填充完成后手动编辑调整

附带脚本

完整实现见 scripts/fill_pdf_form.py，基于 pdfrw 编写。