介绍
# PDF Form Filler
通过编程方式使用文本值和复选框填充 PDF 表单。使用 pdfrw 设置表单字段值，同时保留外观流以确保 PDF 查看器正确渲染。
## 快速开始
使用包含字段名和值的字典填充 PDF 表单：
```python 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": "[email protected]", "Herr": True, # Checkbox "Dienstreise": True, } ) ```
## 功能
- **文本字段**：设置任意文本值（姓名、日期、地址等） - **复选框**：设置布尔值（True 表示选中，False/None 表示未选中） - **外观状态**：正确设置 PDF 查看器渲染所需的 `/On` 和 `/Off` 状态 - **保留结构**：不会剥离表单功能——填充后可继续编辑 - **无依赖**：使用 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()`：
```python 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`：签名字段
## 示例：求职申请表单
```python fill_pdf_form( input_pdf="job_application.pdf", output_pdf="job_application_filled.pdf", data={ "Full Name": "Jane Smith", "Email": "[email protected]", "Phone": "555-1234", "Position": "Software Engineer", "Years Experience": "5", # Checkboxes "Willing to relocate": True, "Available immediately": False, "Background check consent": True, } ) ```
## 高级用法
### 部分填充
仅填充特定字段，其他留空：
```python data = {"Name": "Jane Doe"} # Only Name is set fill_pdf_form("form.pdf", "form_filled.pdf", data) ```
### 动态字段检测
获取所有字段并提示输入值：
```python 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：
```python 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 的完整实现。