PDF表单填充工具

通过编程方式为PDF表单填充文本值和复选框。使用pdfrw库设置表单字段值，同时保留外观流以确保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,  # Checkbox
        "Dienstreise": True,
    }
)

功能特性

• 文本字段：设置任意文本值（姓名、日期、地址等）
• 复选框：设置布尔值（True表示勾选，False/None表示未勾选）
• 外观状态：正确设置/开启和/关闭状态以实现PDF查看器渲染
• 保留结构：不破坏表单功能——可进行后续编辑
• 无依赖项：使用pdfrw库（轻量级、纯Python实现）

工作原理

1. 打开PDF模板
2. 遍历表单字段
3. 为匹配的字段名称设置值
4. 通过同时设置来处理复选框/V（值）和/AS（外观状态）
5. 保存已填写的PDF

字段名称匹配

字段名称应与PDF表单中显示的完全一致。常见模式：

• 德语表单：先生、女士、公务旅行、LfF业务编号
• 英语表单：全名、电子邮件、同意、提交
• 日期字段：日期，出生日期，开始日期

要发现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}")

字段类型：

• 文本：文本输入字段
• 复选框：布尔复选框
• 单选按钮：单选按钮
• 下拉菜单：下拉选择
• 签名：签名字段

示例：求职申请表

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",
        
        # Checkboxes
        "Willing to relocate": True,
        "Available immediately": False,
        "Background check consent": True,
    }
)

高级用法

部分填充

仅填充特定字段，其余留空：

data = {"Name": "Jane Doe"}  # Only Name is set
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"Enter {field_name}: ")
    elif field_type == "checkbox":
        data[field_name] = input(f"Check {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库实现完整功能。