名称： pdf-form-filler
描述： 通过编程方式使用文本值和复选框填充 PDF 表单。适用于需要将数据填入可编辑 PDF 表单（如政府表格、申请表、调查表等）的场景。支持设置文本字段和复选框，并确保外观状态正确，以实现可视化渲染。
版本： 0.2.0

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,  # 复选框
        "Dienstreise": True,
    }
)

功能特性

• 文本字段：设置任意文本值（姓名、日期、地址等）
• 复选框：设置布尔值（True 表示选中，False/None 表示未选中）
• 外观状态：正确设置 /On 和 /Off 状态，确保 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。