pdf-form-fillerlisted

当需要以编程方式读取、填写、勾选或导出 PDF 表单字段，或用一份模板批量套打多份文件时使用本技能。 ## 何时使用 - 读取 PDF 中已有表单字段（字段名、类型、当前值、可选项）。 - 按「字段名 → 值」映射写入文本框、勾选框、单选组、下拉/列表。 - 用一个模板 + 一份数据表（CSV/JSON）批量生成多份已填好的 PDF（套打）。 - 填写后需要锁定字段（flatten）防止二次修改，或保留可编辑表单。 不该用的边界： - PDF 里没有真正的表单字段（只是扫描图/纯文本排版）——那是「在指定坐标叠加文字/图章」，属于 PDF 内容绘制，不属于本技能；需先确认存在 AcroForm/XFA 字段。 - 纯 XFA（动态 XFA、无 AcroForm 兜底）的表单，pypdf/pdf-lib 多数无法可靠写入；遇到先探测，命中纯 XFA 时报告并改用 Adobe/iText 等专用方案，不要硬填。 - 生成全新版式文档（非填表）→ 用 `markdown-to-docx` 等排版技能。 - 从 PDF 抽取正文做问答/总结，不涉及字段写入——不属于本技能。 ## 步骤 / 指令 1. 探测字段：先列出所有字段，确认是 AcroForm 还是 XFA；纯 XFA 直接走边界处理。 2. 建立映射：构造 `{字段名: 值}`；勾选框的值用其「导出值（on 状态名）」而非字面 "true"，导出值从探测结果取。 3. 校验数据：检查必填字段是否齐全、单选/下拉值是否在可选项内、字段名是否存在（拼写/大小写敏感）。 4. 写入：按映射更新字段值；写文本框设 `NeedAppearances` 以保证查看器渲染外观。 5. 处理外观与锁定：需要锁定时 flatten（合并字段为静态内容），否则保留可编辑。 6. 保存为新文件（不覆盖模板），并复读校验关键字段已生效。 7. 批量场景：对数据表每行重复 2–6，输出文件名带行内唯一键。 伪代码（pypdf）： ``` reader = PdfReader("template.pdf") fields = reader.get_fields() # 1. 探测：名/类型/可选项/导出值 assert fields, "无 AcroForm 字段" # 命中即继续，否则按边界处理 data = {"name": "张三", "agree": "/Yes"} # 2. 映射，勾选用导出值 # 3. 校验 for k in data: assert k in fields, f"字段不存在: {k}" writer = PdfWriter(clone_from=reader) for page in writer.pages: writer.update_page_form_field_values( page, data, auto_regenerate=False) # 4. 外观 writer.set_need_appearances_writer(True) with open("out.pdf", "wb") as f: writer.write(f) ``` ## 示例 最小可用——探测字段（命令行）： ``` python -c "from pypdf import PdfReader; import json; print(json.dumps({k:{'type':v.get('/FT')