PyMuPDF 1.24.4 中文文档（十一）（1）

原文：https://pymupdf.readthedocs.io/en/latest/

小部件

原文：pymupdf.readthedocs.io/en/latest/widget.html

此类仅适用于 PDF。

此类表示 PDF 表单字段，也称为“小部件”。在整个文档中，我们将这些术语视为同义词。字段技术上是 PDF 注释的一种特殊情况，允许权限受限的用户在 PDF 中输入信息。主要用于填写表单。

与注释类似，小部件存在于 PDF 页面上。与注释类似，页面上的第一个小部件可通过Page.first_widget访问，后续小部件可通过Widget.next属性访问。

（从版本 1.16.0 中更改） MuPDF 不再将小部件视为一般注释的子集。因此，Page.first_annot 和 Annot.next() 将仅返回非小部件注释，如果页面上仅存在表单字段，则返回None。反之，Page.first_widget 和 Widget.next() 将仅显示小部件。这一设计决策纯粹是 MuPDF 内部的技术性选择；从技术上讲，链接、注释和字段有很多共同之处，并继续在(Py-)MuPDF 内共享它们的大部分代码。

类 API

class Widget

button_states()

新版本 1.18.15 中更改

返回按钮字段可能具有的“开/关”（即选中/未选中或已点击/未点击）状态的名称。虽然“关”状态通常也命名为如此，但“开”状态通常会根据功能上下文命名，例如“是”、“女”等。

此方法有助于查找这些情况下field_value的可能值。

返回：

字典，包含按钮小部件的“开”和“关”在正常和按下外观的名称。以下示例显示“已选择”的值为“男”：

>>> print(field.field_name, field.button_states())
Gender Second person {'down': ['Male', 'Off'], 'normal': ['Male', 'Off']} 

on_state()

• 新版本 1.22.2 中新增

返回复选框和单选按钮的“ON”状态的值。对于复选框，始终是值“是”。对于单选按钮，这是选择/激活按钮的值。

返回：

设置按钮为“已选择”的值。对于非复选框和非单选按钮字段，始终返回None。对于复选框，返回True。对于单选按钮，在以下示例中返回值为“男”：

>>> print(field.field_name, field.button_states())
Gender Second person {'down': ['Male', 'Off'], 'normal': ['Male', 'Off']}
>>> print(field.on_state())
Male 

因此，对于复选框和单选按钮，推荐的设置“已选择”或检查状态的方法如下：

>>> field.field_value = field.on_state()
>>> field.field_value == field.on_state()
True 

update()

对任何小部件进行更改后，必须使用此方法存储到 PDF 中[1]。

reset()

将字段的值重置为其默认值（如果定义了默认值），或将其删除。不要忘记随后执行update()。

next

指向页面上的下一个表单字段。最后一个小部件返回None。

border_color

最多由 4 个浮点数组成的列表，定义字段的边框颜色。默认值为None，导致边框样式和边框宽度被忽略。

border_style

定义字段边框的线条样式。参见Annot.border。默认为“s”（“实线”）– 连续线。在创建小部件时，只有第一个字符（大写或小写）将被视为有效。

border_width

浮点数，定义边框线的宽度。默认为 1。

border_dashes

整数列表/元组，定义边框线的虚线属性。仅在*border_style == “D”*并且提供了border_color时才有意义。

choice_values

定义列表框和组合框的有效选择的 Python 字符串序列。对于这些小部件类型，此属性是强制性的，必须包含至少两个项目。对于其他类型将被忽略。

field_name

必需的字符串，定义字段的名称。不会检查是否重复。

field_label

可选的字符串，包含“备用”字段名称。通常用于任何注释、字段使用帮助等。默认为字段名称。

field_value

字段的值。

field_flags

整数，定义字段的大量属性。更改此属性时请小心，因为可能会更改字段类型。

field_type

必需的整数，定义字段类型。取值范围为 0 到 6。更新小部件时不能更改。

field_type_string

描述（并源自）字段类型的字符串。

fill_color

由最多 4 个浮点数定义的字段背景颜色。

button_caption

按钮类型字段的标题字符串。

is_signed

布尔值，指示签名字段的签名状态，否则为None。

rect

包含字段的矩形。

text_color

由1, 3 或 4 个浮点数组成的列表，定义文本颜色。默认值为黑色([0, 0, 0])。

text_font

定义要使用的字体的字符串。无效值的默认值和替换为*“Helv”*。有关有效字体引用名称，请参见下表。

text_fontsize

定义文本fontsize的浮点数。默认值为零，这会使 PDF 查看器软件动态选择适合注释矩形和文本量的大小。

text_maxlen

定义文本字符的最大数量的整数。PDF 查看器将（应）不接受更长的文本。

text_type

定义可接受文本类型（例如数字、日期、时间等）的整数。目前仅供参考，创建或更新小部件时将被忽略。

xref

小部件的 PDF xref。

script

• 版本 1.16.12 中的新内容

与小部件关联的操作的 JavaScript 文本（Unicode），或None。这是唯一支持的按钮类型小部件的脚本动作。

script_stroke

• 版本 1.16.12 中的新内容

用户在文本字段或组合框中键入键盘按键或修改滚动列表框中的选择时执行的 JavaScript 文本（Unicode）。如果不存在则为None。

script_format

• 版本 1.16.12 中的新内容

在格式化字段以显示其当前值之前执行的 JavaScript 文本（unicode）。此操作可以在格式化之前修改字段的值。如果不存在，则为无。

script_change

• 版本 1.16.12 中的新功能

字段值更改时执行的 JavaScript 文本（unicode）。此操作可以检查新值的有效性。如果不存在，则为无。

script_calc

• 版本 1.16.12 中的新功能

另一个字段的值更改时重新计算此字段值时执行的 JavaScript 文本（unicode）。如果不存在，则为无。

script_blur

• 版本 1.22.6 中的新功能

焦点从此字段移开时执行的 JavaScript 文本（unicode）。如果不存在，则为无。

script_focus

• 版本 1.22.6 中的新功能

聚焦此字段时执行的 JavaScript 文本（unicode）。如果不存在，则为无。

注释

1. 添加或更改上述脚本之一时，

只需将适当的 JavaScript 源代码放入小部件属性中。要删除脚本，请将相应属性设置为无。

1. 按钮字段仅支持script。

其他脚本条目将自动设置为无。

1. 值得一看的是这个手册，其中包含有关 Adobe 各种字段类型的标准脚本的大量信息。例如，如果要添加表示日期的文本字段，可以存储以下脚本。它们将确保与模式兼容的日期格式，并在支持的查看器中显示日期选择器：

widget.script_format = 'AFDate_FormatEx("mm/dd/yyyy");'
widget.script_stroke = 'AFDate_KeystrokeEx("mm/dd/yyyy");' 

小部件的标准字体

小部件使用自己的资源对象*/DR*。小部件资源对象必须至少包含一个*/Font*对象。小部件字体与页面字体独立。我们目前支持以下固定参考名称使用的 14 个 PDF 基本字体，或者使用任何已存在的字段字体名称。在指定新的或更改的小部件的文本字体时，要么选择第一列中的一个（支持大写和小写），要么选择已存在的表单字体之一。在后一种情况下，拼写必须完全匹配。

要查找已存在的字段字体，请检查列表Document.FormFonts。

通常可以为每个小部件自由选择任何字体。但是，我们建议对复选框使用ZaDb（“ZapfDingbats”）和fontsize 0：典型的查看器在单击时会在字段的矩形中放置正确大小的勾号。

支持的小部件类型

PyMuPDF 支持创建和更新许多小部件类型，但不是全部。

• 文本（PDF_WIDGET_TYPE_TEXT）
  
• 按钮（PDF_WIDGET_TYPE_BUTTON）
  
• 复选框（PDF_WIDGET_TYPE_CHECKBOX）
  
• 下拉框（PDF_WIDGET_TYPE_COMBOBOX）
  
• 列表框（PDF_WIDGET_TYPE_LISTBOX）
  
• 单选按钮（PDF_WIDGET_TYPE_RADIOBUTTON）：PyMuPDF 目前不支持创建（互相连接的）单选按钮组，设置一个按钮会自动取消设置组中的其他按钮。小部件对象也不反映按钮组的存在。然而：支持一致地选择（或取消选择）单选按钮。这包括正确设置维护在所属按钮组中的值。选择单选按钮可以通过分配True或field.on_state()给字段值来完成。取消选择按钮应该通过分配False来完成。
  
• 签名（PDF_WIDGET_TYPE_SIGNATURE）只读。
  

脚注

你对本页面有什么反馈吗？

本软件按原样提供，不附带任何明示或暗示的保证。本软件在许可下分发，除非在该许可的条款下明确授权，否则不得复制、修改或分发本软件。请参阅artifex.com上的许可信息，或联系美国加利福尼亚州旧金山 Mesa Street 39 号 108A 单元的 Artifex Software Inc. 了解更多信息。

本文档覆盖了所有版本直到 1.24.4。

小部件的标准字体

小部件使用自己的资源对象*/DR*。小部件资源对象必须至少包含一个*/Font*对象。小部件字体独立于页面字体。我们目前支持使用以下固定参考名称的 14 种 PDF 基本字体，或者任何现有字段字体的名称。在指定新的或更改的小部件的文本字体时，要么选择第一张表列中的一个（支持大小写），要么选择已经存在的表单字体之一。在后一种情况下，拼写必须完全匹配。

要找出已经存在的字段字体，请检查列表Document.FormFonts。

通常，你可以为每个小部件自由选择任何字体。然而，我们建议对于复选框使用ZaDb（“ZapfDingbats”）和fontsize 0：典型的查看器会在单击字段的矩形时放置一个正确大小的勾号。

支持的小部件类型

PyMuPDF 支持创建和更新许多小部件类型，但不是所有类型都支持。

• 文本框（PDF_WIDGET_TYPE_TEXT）
  
• 按钮（PDF_WIDGET_TYPE_BUTTON）
  
• 复选框（PDF_WIDGET_TYPE_CHECKBOX）
  
• 下拉框（PDF_WIDGET_TYPE_COMBOBOX）
  
• 列表框（PDF_WIDGET_TYPE_LISTBOX）
  
• 单选按钮（PDF_WIDGET_TYPE_RADIOBUTTON）：PyMuPDF 目前不支持创建（相互连接的）单选按钮组，其中设置一个按钮会自动取消组中的其他按钮。小部件对象也不反映按钮组的存在。然而，可以一致地选择（或取消选择）单选按钮。这包括正确设置所属按钮组中维护的值。选择单选按钮可以通过将 True 或 field.on_state() 分配给字段值来完成。取消选择按钮应通过分配 False 来完成。
  
• 签名（PDF_WIDGET_TYPE_SIGNATURE）只读。
  

脚注

您对本页面有任何反馈吗？

本软件按“原样”提供，不带任何明示或默示的保证。此软件根据许可分发，除非根据许可条款明确授权，否则不得复制、修改或分发。有关详细信息，请参阅 artifex.com 的许可信息或联系美国旧金山 CA 94129 Mesa 街 39 号 108A 套房的 Artifex Software Inc.。

本文档涵盖了所有版本直至 1.24.4。

PyMuPDF 1.24.4 中文文档（十一）（2）https://developer.aliyun.com/article/1559462