使用PyMuPDF(fitz)设置Widget的field_value不生效该如何处理？

我编写了一个用于填充PDF中AcroForms的简单脚本，控制台输出显示fieldValue1和fieldValue2均正常，但保存后的PDF表单字段中无填充值。请问如何确保设置的值能被正确保存到输出PDF中？

import fitz  # PyMuPDF

def fill_pdf_form(input_pdf, output_pdf, data):
    doc = fitz.open(input_pdf)

    for page_num in range(len(doc)):
        page = doc.load_page(page_num)
        for widget in page.widgets():
            field_name = widget.field_name
            print("fieldName: ", field_name)
            if field_name in data:
                widget.field_value = data[field_name]
                print("fieldValue1: ", data[field_name])
                print("fieldValue2: ", widget.field_value)

    doc.save(output_pdf, use_objstms=1)
    doc.close()


if __name__ == "__main__":
    input_pdf = "file.pdf"
    output_pdf = "file_filled.pdf"
    data = {
        "field_01": "123456 _ggtl",
        "field_multiline_01": "lorem Ipsum\nnext line\nagain a line",
    }
    fill_pdf_form(input_pdf, output_pdf, data)
    print(f"success: {output_pdf}")

问题核心是修改字段值后未触发PyMuPDF的更新机制，导致变更没有被写入最终PDF。只需做两处调整：

1. 设置字段值后调用widget.update()：显式告知PyMuPDF字段已修改，同步变更到文档对象
2. 调整保存参数：使用garbage=3确保表单修改被持久化，可配合或替换原有的use_objstms参数

修改后的完整代码：

import fitz  # PyMuPDF

def fill_pdf_form(input_pdf, output_pdf, data):
    doc = fitz.open(input_pdf)

    for page_num in range(len(doc)):
        page = doc.load_page(page_num)
        for widget in page.widgets():
            field_name = widget.field_name
            print("fieldName: ", field_name)
            if field_name in data:
                widget.field_value = data[field_name]
                widget.update()  # 新增：标记字段变更
                print("fieldValue1: ", data[field_name])
                print("fieldValue2: ", widget.field_value)

    # 修改保存参数，确保表单变更被写入
    doc.save(output_pdf, garbage=3)
    doc.close()


if __name__ == "__main__":
    input_pdf = "file.pdf"
    output_pdf = "file_filled.pdf"
    data = {
        "field_01": "123456 _ggtl",
        "field_multiline_01": "lorem Ipsum\nnext line\nagain a line",
    }
    fill_pdf_form(input_pdf, output_pdf, data)
    print(f"success: {output_pdf}")

关键说明 #

• widget.update()：这是必须步骤，仅设置field_value不会自动同步到PDF底层结构，调用该方法后变更才会被记录
• garbage=3：执行文档垃圾回收，清理无效对象的同时确保所有表单字段的修改被正确持久化，替代或配合use_objstms=1使用均可

内容的提问来源于stack exchange，提问作者bitkorn