form-filler

表单填写器

使用结构化数据以编程方式填写 PDF 表单。

功能

• 字段检测：自动检测表单字段
• 多种字段类型：文本、复选框、下拉菜单、单选按钮
• 数据来源：JSON、CSV、字典输入
• 批量填写：根据数据文件填写多个表单
• 字段映射：将数据键映射到字段名称
• 扁平化选项：转换为不可编辑的 PDF
• 表单信息：列出所有字段及其类型

快速开始

from form_filler import FormFiller

filler = FormFiller()

# Load form
filler.load("application_form.pdf")

# Fill fields
filler.fill({
    "name": "John Doe",
    "email": "[email protected]",
    "date": "2024-01-15",
    "agree": True  # Checkbox
})

# Save filled form
filler.save("filled_form.pdf")

CLI 用法

# Fill from JSON data
python form_filler.py --input form.pdf --data data.json --output filled.pdf

# List form fields
python form_filler.py --input form.pdf --list-fields

# Fill from CSV (batch)
python form_filler.py --input form.pdf --batch data.csv --output-dir filled/

# Flatten filled form
python form_filler.py --input form.pdf --data data.json --flatten --output filled.pdf

# With field mapping
python form_filler.py --input form.pdf --data data.json --mapping mapping.json -o filled.pdf

API 参考

FormFiller 类

class FormFiller:
    def __init__(self)

    # Loading
    def load(self, filepath: str) -> 'FormFiller'

    # Field Operations
    def list_fields(self) -> List[Dict]
    def get_field_info(self, field_name: str) -> Dict
    def get_field_value(self, field_name: str) -> Any

    # Filling
    def fill(self, data: Dict) -> 'FormFiller'
    def fill_field(self, name: str, value: Any) -> 'FormFiller'
    def fill_from_json(self, filepath: str) -> 'FormFiller'
    def fill_from_csv_row(self, row: Dict) -> 'FormFiller'

    # Field Mapping
    def set_mapping(self, mapping: Dict[str, str]) -> 'FormFiller'

    # Output
    def save(self, filepath: str, flatten: bool = False) -> str
    def flatten(self) -> 'FormFiller'

    # Batch Processing
    def batch_fill(self, input_form: str, data_file: str,
                  output_dir: str) -> List[str]

字段类型

文本字段

filler.fill({
    "first_name": "John",
    "last_name": "Doe",
    "address": "123 Main St"
})

复选框

filler.fill({
    "agree_terms": True,
    "subscribe": False
})

单选按钮

filler.fill({
    "gender": "male",  # Value of selected option
    "payment_method": "credit_card"
})

下拉菜单

filler.fill({
    "country": "USA",
    "state": "California"
})

字段发现

fields = filler.list_fields()
# Returns:
# [
#     {"name": "first_name", "type": "text", "required": True},
#     {"name": "agree_terms", "type": "checkbox", "value": False},
#     {"name": "country", "type": "dropdown", "options": ["USA", "Canada", "UK"]}
# ]

字段映射

将数据键映射到表单字段名称：

filler.set_mapping({
    "fname": "first_name",     # data key -> form field
    "lname": "last_name",
    "addr": "address_line_1"
})

filler.fill({
    "fname": "John",           # Uses mapping
    "lname": "Doe"
})

批量填写

从 CSV 填写

# CSV format:
# first_name,last_name,email
# John,Doe,[email protected]
# Jane,Smith,[email protected]

filler.batch_fill(
    input_form="application.pdf",
    data_file="applicants.csv",
    output_dir="filled_forms/"
)
# Creates: filled_forms/application_0.pdf, application_1.pdf, ...

从 JSON 数组填写

# JSON format:
# [
#     {"first_name": "John", "last_name": "Doe"},
#     {"first_name": "Jane", "last_name": "Smith"}
# ]

filler.batch_fill(
    input_form="form.pdf",
    data_file="data.json",
    output_dir="output/"
)

依赖项

• PyMuPDF>=1.23.0
• pillow>=10.0.0
• pandas>=2.0.0