Python实现PDF表单域自动化创建与智能填充功能_Python

在很多业务场景中，pdf 表单不仅仅是展示模板，更是数据采集与流转的关键载体。相比传统“打印—填写—扫描”的方式，交互式 pdf 表单可以让用户直接在线填写并提交数据，大幅提升信息收集效率。

无论是问卷调查、客户登记，还是入职申请表，只要表单结构设计合理，就可以实现数据的自动化采集与管理。本文将介绍如何使用 spire.pdf for python 创建可填写的 pdf 表单，并进一步实现自动填充。

一、安装 spire.pdf for python

本教程依赖：

spire.pdf for python
plum-dispatch v1.7.4（底层方法分发支持）

安装方式如下：

pip install spire.pdf

该库还为小型项目提供了免费版：pip install spire.pdf.free

如果你在 windows 环境下安装遇到问题，可以参考官方安装说明文档。

在创建 pdf 表单之前，我们需要理解一个核心结构：

pdfform —— 表示整个交互式表单
pdffield —— 表示单个字段
各类字段对象 —— 表示不同类型的表单控件

spire.pdf 提供了丰富的字段类型，常用的包括：

类名	说明	常用属性
pdftextboxfield	文本框，用于录入姓名、地址等	`bounds`, `font`, `text`
pdfcheckboxfield	复选框，用于多选场景	`checked` (true/false)
pdfradiobuttonlistfield	单选按钮组，互斥选项	`items`, `selectedindex`
pdfcomboboxfield	组合框（下拉列表）	`items`, `font`
pdfbuttonfield	提交/重置按钮	`actions.mousedown`

在多数业务表单中，基本就是这些类型的组合。

三、表单创建的整体流程与实现思路

在了解了不同表单域类型及其用途之后，下一步就是把这些字段真正组织成一份可用的 pdf 表单。从实现角度来看，表单创建并不复杂，本质上就是先搭好文档结构，再逐步往里放入字段控件。只要流程清晰，后续扩展或调整字段都会非常轻松。

创建表单的基本步骤如下：

创建 pdfdocument
添加页面
创建字段对象
设置字段位置（bounds）
添加到 doc.form.fields
保存文档

下面我们通过一个简单的示例，构建一份员工入职登记表模板，包含文本输入、材料清单复选、性别单选以及部门与职位级别的下拉选择控件：

from spire.pdf.common import *
from spire.pdf import *
# 初始化文档
doc = pdfdocument()
page = doc.pages.add()
# 定义布局基准坐标
basex = 120.0
basey = 40.0
brush_title = pdfsolidbrush(pdfrgbcolor(color.get_darkblue()))
brush_text = pdfsolidbrush(pdfrgbcolor(color.get_black()))
# 设置字体
font = pdftruetypefont("宋体", 11.0, pdffontstyle.regular, true)
# 1. 文本框：姓名
page.canvas.drawstring("员工姓名：", font, brush_title, pointf(10.0, basey))
txt_name = pdftextboxfield(page, "empname")
txt_name.bounds = rectanglef(basex, basey, 160.0, 16.0)
txt_name.font = font
doc.form.fields.add(txt_name)
# 2. 复选框：入职材料清单
basey += 35.0
page.canvas.drawstring("提交材料：", font, brush_title, pointf(10.0, basey))
# 选项一：身份证
cb_id = pdfcheckboxfield(page, "doc_id")
cb_id.bounds = rectanglef(basex, basey, 16.0, 16.0)
doc.form.fields.add(cb_id)
page.canvas.drawstring("身份证复印件", font, brush_text, pointf(basex + 22.0, basey))
# 选项二：学历学位证书
cb_edu = pdfcheckboxfield(page, "doc_edu")
cb_edu.bounds = rectanglef(basex + 100.0, basey, 16.0, 16.0)
doc.form.fields.add(cb_edu)
page.canvas.drawstring("学历学位证书", font, brush_text, pointf(basex + 122.0, basey))
# 3. 单选按钮：性别
basey += 35.0
page.canvas.drawstring("性别：", font, brush_title, pointf(10.0, basey))
rb_gender = pdfradiobuttonlistfield(page, "gender")
item_m = pdfradiobuttonlistitem("男")
item_m.bounds = rectanglef(basex, basey, 16.0, 16.0)
page.canvas.drawstring("男", font, brush_text, pointf(basex + 22.0, basey))
item_f = pdfradiobuttonlistitem("女")
item_f.bounds = rectanglef(basex + 60.0, basey, 16.0, 16.0)
page.canvas.drawstring("女", font, brush_text, pointf(basex + 82.0, basey))
rb_gender.items.add(item_m)
rb_gender.items.add(item_f)
doc.form.fields.add(rb_gender)
# 4. 组合框：所属部门
basey += 35.0
page.canvas.drawstring("入职部门：", font, brush_title, pointf(10.0, basey))
cmb_dept = pdfcomboboxfield(page, "dept")
cmb_dept.bounds = rectanglef(basex, basey, 160.0, 16.0)
cmb_dept.items.add(pdflistfielditem("研发部", "rd"))
cmb_dept.items.add(pdflistfielditem("市场部", "mkt"))
cmb_dept.items.add(pdflistfielditem("行政部", "admin"))
cmb_dept.font = font
doc.form.fields.add(cmb_dept)
# 5. 组合框：职位级别
basey += 35.0
page.canvas.drawstring("职位级别：", font, brush_title, pointf(10.0, basey))
cmb_level = pdfcomboboxfield(page, "joblevel")
cmb_level.bounds = rectanglef(basex, basey, 160.0, 16.0)
cmb_level.items.add(pdflistfielditem("初级 (p1-p2)", "junior"))
cmb_level.items.add(pdflistfielditem("中级 (p3-p5)", "senior"))
cmb_level.items.add(pdflistfielditem("高级 (p6+)", "expert"))
cmb_level.font = font
doc.form.fields.add(cmb_level)
# 6. 保存模板
doc.savetofile("/output/入职表.pdf")
doc.close()

spire.pdf for python 创建的 pdf 表单域预览：

四、python 填充 pdf 表单的实现思路与流程

在完成 pdf 表单模板的创建之后，下一步就是通过程序自动写入数据，例如员工信息、系统导出的业务数据等。相比手动填写，程序化填充不仅效率更高，也更适合批量处理和自动化场景。下面从整体流程入手，说明 python 填充 pdf 表单域的核心思路。

填充流程的核心逻辑是：

加载 pdf
获取表单对象
获取字段集合
根据字段类型和名称进行赋值

在前一节中，我们已经通过代码创建了一个包含多种表单控件的 pdf 入职表。接下来，我们将基于这个已创建的表单，演示如何使用 python 自动为各类表单域赋值，实现入职信息的批量或程序化填写。

下面的示例代码以该入职表为例，分别对文本框、复选框、单选按钮和组合框等字段进行填充，并最终生成一份已填写完成的 pdf 入职表。

from spire.pdf.common import *
from spire.pdf import *
# 1. 加载文档
doc = pdfdocument()
doc.loadfromfile("/output/入职表.pdf")
# 2. 获取表单字段集合
form = doc.form
try:
    formwidget = pdfformwidget(form)
    fields = formwidget.fieldswidget
except:
    fields = form.fieldswidget
# 3. 遍历并填充字段
if fields is not none and fields.count > 0:
    for i in range(fields.count):
        field = fields.get_item(i)
        name = field.name
        # 文本框
        if isinstance(field, pdftextboxfieldwidget):
            if name == "empname":
                field.text = "张岚"
        # 复选框
        if isinstance(field, pdfcheckboxwidgetfieldwidget):
            if name == "doc_id" or name == "doc_edu":
                field.checked = true
        # 单选按钮
        if isinstance(field, pdfradiobuttonlistfieldwidget):
            if name == "gender":
                field.selectedindex = 1
        # 组合框
        if isinstance(field, pdfcomboboxwidgetfieldwidget):
            if name == "dept":
                field.selectedindex = [0]
            if name == "joblevel":
                field.selectedindex = [2]
# 4. 保存文档
doc.savetofile("/output/员工入职表1-1.pdf")
doc.close()
print("填充任务已顺利完成！")

填充完成后的 pdf 文件预览：