小部件#

该类仅用于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值。

returns:

一个字典，包含按钮小部件的正常和被按下外观的“开”和“关”的名称。以下示例显示“所选”值为“男性”:

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

  • 1.22.2版本的新特性

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

returns:

设置按钮为“选中”的值。对于非复选框、非单选框字段，总是返回None。对于复选框，返回True。对于单选按钮，在以下示例中这是值“Male”：

>>> 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#

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

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），或无。这是按钮类型小部件支持的唯一脚本操作。

script_stroke#

  • 在版本 1.16.12 中的新功能

在用户在文本字段或组合框中输入按键或修改可滚动列表框中的选择时，将执行JavaScript文本（unicode）。此操作可以检查按键的有效性并拒绝或修改它。如果不存在，无。

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

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

小部件的标准字体#

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

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

参考

Base14 字体名称

CoBI

快递-粗体斜体

CoBo

快递-粗体

合作信息科技

Courier-倾斜

法院

信使

HeBI

Helvetica-Bold斜体

和博

Helvetica-Bold

HeiIt

Helvetica-倾斜

赫尔维

Helvetica (默认)

符号

符号

TiBI

时代-粗体斜体

蒂博

粗体时间

标题

斜体字

TiRo

时代罗马

ZaDb

扎普夫丁巴茨

您通常可以为每个小部件使用任何字体。 然而，我们建议使用 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或联系Artifex Software Inc.，地址：39 Mesa Street, Suite 108A, San Francisco CA 94129, United States以获取更多信息。

此文档涵盖所有版本，直到1.25.2。