pdf-form-filler

核心用法

pdf-form-filler 是一款专注于 PDF 表单自动填充的 Python 工具，通过 fill_pdf_form()() 函数实现程序化填表。用户只需提供输入 PDF 路径、输出路径以及包含字段名-值对的字典，即可完成填充。支持两种主要字段类型：文本字段（任意字符串值）和复选框（布尔值控制选中状态）。工具同时提供 list_pdf_fields()() 辅助函数，用于探测 PDF 中的可用字段名称和类型，解决表单字段名难以识别的问题。

显著优点

1. 零依赖负担：仅依赖 pdfrw 一个轻量级纯 Python 库，无系统级依赖，安装部署极为简便。
2. 视觉渲染正确：正确处理 PDF 表单的 /V（值）和 /AS（外观状态）属性，确保在 Adobe Reader、Firefox 等主流阅读器中正确显示。
3. 表单功能保留：填充后的 PDF 仍保留表单可编辑性，用户可后续手动调整。
4. 批量处理能力：结合 Python 循环可轻松实现多份表单的批量填充，显著提升行政办公效率。
5. 学术背景可信：开发者使用德国埃尔朗根-纽伦堡大学学术邮箱，代码开源透明，MIT 许可证授权。

潜在缺点与局限性

• 复选框显示兼容性：部分 PDF 阅读器（如某些版本的 Chrome 内置阅读器）可能无法立即渲染复选框状态，需使用 Adobe Reader 或 Firefox 查看。
• 字段名敏感：必须精确匹配 PDF 内部字段名，部分表单使用无意义的机器生成名称（如 Field_1），需先用探测函数确认。
• 文本截断问题：若 PDF 模板字段宽度不足，长文本可能被截断，需预先调整模板或控制输入长度。
• 功能单一：仅支持文本和复选框，不支持下拉菜单、单选按钮组、数字签名等高级表单元素。

适合的目标群体

• 行政办公人员：需要批量处理入职申请、报销单、政府申报表等重复性表单填写工作。
• HR 与招聘团队：自动化处理大量求职者申请表的信息录入。
• 开发者与自动化工程师：构建文档工作流，将 PDF 填表集成到更大的业务系统中。
• 学术与研究机构：处理标准化的实验申请、伦理审查表等学术文档。

使用风险

• 文件路径安全：工具直接操作用户指定的文件路径，需确保输入 PDF 来源可信，避免处理恶意构造的 PDF 文件。
• 输出覆盖风险：若输出路径与现有文件重名，将直接覆盖，建议在批量处理时做好文件备份或路径规划。
• 依赖维护状态：pdfrw 虽成熟稳定，但更新频率较低，长期需关注其兼容性维护情况。

核心用法

pdf-form-filler 是一款基于 pdfrw 的轻量级 PDF 表单填充工具，通过纯 Python 代码实现可编程化表格填写。核心功能围绕 fill_pdf_form() 函数展开，用户只需提供输入 PDF 模板、输出路径及字段-值映射字典，即可完成自动化填充。支持文本字段（姓名、日期、地址等）和布尔型复选框（通过 True/False 控制选中状态），并正确处理 PDF 内部的 /V（值）和 /AS（外观状态）属性以确保视觉渲染。

辅助函数 list_pdf_fields() 可扫描并列出 PDF 中所有表单字段及其类型（text/checkbox/radio/dropdown/signature），帮助用户精准匹配字段名——这对处理德语表单（如 Herr/Dienstreise）或命名不规范的字段尤为重要。

显著优点

1. 零网络依赖，隐私安全：纯本地运行，无外部 API 调用，敏感数据（如身份证号、银行信息）不出本地，天然符合 GDPR/CCPA 合规要求。
2. 单依赖轻量化：仅依赖 pdfrw 一个成熟开源库（纯 Python，无二进制扩展），安装简便，无供应链攻击风险。
3. 保留表单可编辑性：填充后的 PDF 仍保留表单结构，用户可二次手动调整，区别于某些"压平"（flatten）方案。
4. 批量处理能力：支持循环调用实现多文件批量填充，适合 HR 批量生成合同、财务批量填写报销单等场景。

潜在缺点与局限性

1. 视觉渲染兼容性：部分 PDF 阅读器（尤其是精简版移动端 App）可能无法正确显示复选框选中状态，尽管数据已正确写入。Adobe Reader、Firefox、evince/okular 兼容性最佳。
2. 字段类型限制：当前主要支持文本和复选框，对下拉框（dropdown）、单选按钮（radio）、数字签名字段的填充支持有限或需额外开发。
3. 排版不可控：若原 PDF 字段宽度不足，长文本会被截断，无法自动调整字体大小或换行，需预处理模板或后期人工修正。
4. 输入验证薄弱：缺乏对字段存在性、类型匹配、路径合法性的严格校验，错误字段名会导致静默失败或异常。

适合人群

• 行政/HR 人员：批量生成标准化入职、报销、审批表格
• 开发者/自动化工程师：集成至 RPA 或 CI/CD 流程，实现文档自动化
• 个人用户：重复填写政府表格（签证、税务申报等），减少手工操作
• 数据隐私敏感场景：必须本地处理、禁止上传云端的企业环境

常规风险

• 来源可信度 T3：作者为个人开发者 raulsimpetru，虽代码开源透明，但缺乏企业背书。关键业务建议审计代码或优先选用 T1/T2 来源工具。
• PDF 模板依赖：工具行为受原 PDF 表单质量制约，字段命名混乱、结构嵌套复杂的模板可能需人工预处理。
• 输出文件管理：未自动创建输出目录，路径错误时可能抛出异常，需调用方确保环境就绪。