填充 XFA PDF 表单

通过命令行（CLI）填充任意 Adobe LiveCycle XFA 表单。填补了标准 PDF 工具无法解决的空白。

为何需要此工具

XFA 表单（pdfinfo 输出中显示为 Form: XFA）将数据以 XML 形式嵌入 PDF 内部，而非使用标准 AcroForm 字段。诸如 pdftk、pypdf 和 PyPDF2 等工具会静默失败或输出空结果。本脚本直接修改嵌入的 XFA XML 内容。

前提条件

pip install pikepdf

快速开始

SCRIPT="/scripts/fill_xfa.py"

# 1) 验证表单是否为 XFA 格式：
pdfinfo form.pdf | grep Form  # 应显示：Form: XFA

# 2) 发现字段名称：
python3 "$SCRIPT" fields form.pdf

# 3) 从 JSON 填充表单：
python3 "$SCRIPT" fill form.pdf -o filled.pdf -d data.json

命令

fields — 列出数据字段

python3 "$SCRIPT" fields form.pdf

输出按字母顺序排序的字段名，并附带当前值及重复出现次数。

fill — 设置字段值

支持三种输入方式，可自由组合使用：

# 可重复使用的 --set 参数：
python3 "$SCRIPT" fill form.pdf -o out.pdf 
  --set "Eigentümer_Name=Müller" 
  --set "Eigentümer_Vorname=Anna" 
  --set "PLZ=84424"

# JSON 文件：
python3 "$SCRIPT" fill form.pdf -o out.pdf -d fields.json

# 通过 stdin 管道输入：
printf '{"Name":"Müller","Vorname":"Anna"}' | 
  python3 "$SCRIPT" fill form.pdf -o out.pdf --stdin

JSON 数据格式

{
  "Feldname": "Wert",
  "Eigentümer_Name": "Müller",
  "Datum": "2026-05-05"
}

字段名必须与表单中 XML 元素的名称完全一致（可通过 fields 命令发现）。

重复字段

某些表单会复用字段名（例如多个 Textfeld1）。支持两种模式：

• 所有位置设为相同值： --set Textfeld1=3 将所有同名字段设为 "3"
• 每个重复项设为不同值： 传入数组：{"Textfeld1": ["A", "B", "C"]}，值将按顺序分配给各重复字段（第一个字段得 "A"，第二个得 "B"，依此类推）

限制条件

• 仅适用于 XFA 表单 —— 请先验证：pdfinfo form.pdf | grep Form
• 表单不得受密码保护
• 命名空间恢复仅保留首个 xmlns:* 声明（通常不影响使用）
• 部分表单在填充后仍需手写签名（wet-ink signature）

常见使用场景

• 政府注册类表单（德语：Behördendrucke，如 Landkreis 下发的各类表格）
• 公用事业公司表单（垃圾清运、水电等）
• 学校入学申请表
• 从官方网站下载的任意 Adobe LiveCycle Designer 表单

示例：德国垃圾桶注册表单（Tonnenanmeldung）

# 发现字段：
python3 "$SCRIPT" fields tonnenanmeldung_blank.pdf

# 从 JSON 填充（通过 stdin 管道输入）：
python3 "$SCRIPT" fill tonnenanmeldung_blank.pdf -o tonnenanmeldung_filled.pdf --stdin <<'EOF'
{
  "Neuantrag": "1",
  "Eigentümer_Name": "Müller",
  "Eigentümer_Vorname": "Anna",
  "Eigentümer_Straße": "Hauptstraße",
  "Eigentümer_Straße_Nummer": "5",
  "Eigentümer_PLZ": "84424",
  "Eigentümer_Ort": "Isen",
  "Eigentümer_seit": "2026-01-15",
  "Grundstück_Straße": "Beispielweg",
  "Grundstück_PLZ": "85435",
  "Grundstück_Ort": "Erding",
  "Grundstück_Haus_Nummer": "12",
  "Textfeld1": "3",
  "Restmüll_ab": "07/2026",
  "Zugang_80_l": "1",
  "Bio_Zugang_80_l": "1",
  "Papier_Zugang_240_l": "1",
  "Kontoinhaber_Name": "Müller, Anna",
  "Kontoinhaber_Straße": "Hauptstraße 5",
  "Kontoinhaber_Ort": "84424 Isen",
  "Kontoinhaber_Kreditinstitut": "VR-Bank",
  "Kontoinhaber_IBAN": "DE",
  "Kontoinhaber_IBAN_Nummer": "1234567890",
  "Kontoinhaber_BIC": "GENODEF1XXX",
  "Datum": "2026-05-05"
}
EOF