English日本語

在 Discord 上找到 #pymupdf

Widget

此类仅适用于 PDF。

此类表示 PDF 表单字段，也称为“widget”。在整个文档中，我们互换使用这些术语。从技术上讲，字段是 PDF 注释的一种特殊情况，它允许权限有限的用户在 PDF 中输入信息。这主要用于填写表单。

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

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

类 API

class Widget

button_states()

版本 1.18.15 中的新功能

返回按钮字段可能具有的开/关（即选中/点击或未点击）状态名称。通常‘Off’状态也以此命名，而‘On’状态通常会根据功能上下文命名，例如‘Yes’、‘Female’等。

此方法有助于在这种情况下找出 field_value 的可能值。

返回：

一个字典，包含按钮 widget 的正常外观和按下外观的‘On’和‘Off’状态名称。以下示例显示“选中”的值是“Male”

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

on_state()

• 版本 1.22.2 中的新功能

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

返回：

将按钮设置为“选中”的值。对于非复选框、非单选按钮字段，始终返回 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(sync_flags=False)

对 widget 进行任何更改后，必须使用此方法来反映 PDF 中的更改 [1]。

参数：

sync_flags (bool) – 如果为 True，widget 的 Widget.field_flags 将复制到 Parent 对象（如果存在）及其 Kids 数组中命名的所有 widget。这提供了一种方便的方式，例如，将 widget 的所有实例设置为只读，无论它们出现在哪个页面上 [2]。

reset()

将字段的值重置为其默认值（如果已定义），或将其移除。之后不要忘记调用 update()。

next

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

border_color

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

border_style

一个字符串，定义字段边框的线条样式。参见 Annot.border。默认是“s”（“Solid”）——一条连续线。创建 widget 时只考虑第一个字符（大写或小写）。

border_width

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

border_dashes

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

choice_values

定义列表框和组合框有效选项的 Python 字符串序列。对于这些 widget 类型，此属性是必需的，并且必须包含至少两个项。对其他类型忽略。

field_name

一个必需的字符串，定义字段的名称。不进行重复检查。

field_label

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

field_value

字段的值。

field_flags

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

field_type

一个必需的整数，定义字段类型。这是一个在 0 到 6 范围内的值。更新 widget 时无法更改它。

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

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

xref

widget 的 PDF xref。

script

• 版本 1.16.12 中的新功能

与 widget 关联的操作的 JavaScript 文本 (unicode)，或 None。这是按钮类型 widget 唯一支持的脚本操作。

script_stroke

• 版本 1.16.12 中的新功能

当用户在文本字段或组合框中键入击键或修改可滚动列表框中的选择时要执行的 JavaScript 文本 (unicode)。此操作可以检查击键的有效性并拒绝或修改它。如果不存在，则为 None。

script_format

• 版本 1.16.12 中的新功能

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

script_change

• 版本 1.16.12 中的新功能

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

script_calc

• 版本 1.16.12 中的新功能

当另一个字段的值更改时，要执行的用于重新计算此字段值的 JavaScript 文本 (unicode)。如果不存在，则为 None。

script_blur

• 版本 1.22.6 中的新功能

失去此字段焦点时要执行的 JavaScript 文本 (unicode)。如果不存在，则为 None。

script_focus

• 版本 1.22.6 中的新功能

获得此字段焦点时要执行的 JavaScript 文本 (unicode)。如果不存在，则为 None。

注意

1. 要添加或更改以上某个脚本，

只需将相应的 JavaScript 源代码放入 widget 属性中即可。要移除脚本，请将相应属性设置为 None。

2. 按钮字段仅支持 script。

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

3. 查阅 这份 手册很有价值，其中包含大量关于 Adobe 针对各种字段类型的标准脚本的信息。例如，如果您想添加一个表示日期的文本字段，您可能需要存储以下脚本。它们将确保模式兼容的日期格式，并在支持的查看器中显示日期选择器

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

Widget 的标准字体

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

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

引用名称	Base14 字体名称
CoBI	Courier-BoldOblique
CoBo	Courier-Bold
CoIt	Courier-Oblique
Cour	Courier
HeBI	Helvetica-BoldOblique
HeBo	Helvetica-Bold
HeIt	Helvetica-Oblique
Helv	Helvetica (默认)
Symb	Symbol
TiBI	Times-BoldItalic
TiBo	Times-Bold
TiIt	Times-Italic
TiRo	Times-Roman
ZaDb	ZapfDingbats

通常您可以使用任何字体用于每个 widget。但是，对于复选框，我们建议使用 ZaDb (“ZapfDingbats”) 和 fontsize 0：典型的查看器在点击时会在字段的矩形中放入一个大小正确的勾号。

支持的 Widget 类型

PyMuPDF 支持创建和更新许多 widget 类型，但不是所有类型。

• 文本 (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 目前不支持创建单选按钮组（相互连接的），其中设置一个按钮会自动取消设置组中的其他按钮。widget 对象也不反映按钮组的存在。但是：支持一致地选择（或取消选择）单选按钮。这包括正确设置所属按钮组中维护的值。可以通过将 True 或 field.on_state() 赋给字段值来选择单选按钮。取消选择按钮应通过赋 False 来完成。

• 签名 (PDF_WIDGET_TYPE_SIGNATURE) 只读 – 不支持更新或创建签名。

脚注

[1]

如果您打算重新访问新的或更新的字段（例如制作一个 pixmap），请确保先重新加载页面。可以关闭并重新打开文档，或者先加载另一个页面，或者简单地执行 page = doc.reload_page(page)。

[2]

除了其他用途外，Parent 对象也用于方便字段的多次出现（在同一页面或不同页面上）。此 Parent 对象中的 Kids 数组包含所有作为同一字段“副本”的 widget 的交叉引用。每当任何“kid” widget 的字段值更改时，所有其他 kids 也会立即更新。这是一种非常有效的方式来处理同一字段的多个副本，例如用于填写表单。这种同步更新仅针对 Widget.field value 发生。新参数 sync_flags 将此功能扩展到 Widget.field_flags。为了提供更大的灵活性，这不能像字段值那样自动化处理。

---

本软件按“现状”提供，不带任何明示或暗示的担保。本软件在许可下分发，除非根据该许可条款明确授权，否则不得复制、修改或分发。有关许可信息，请参阅 artifex.com 或联系 Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States 获取更多信息。

本文档涵盖所有版本，直至 1.26.0。