Annot#

此类仅适用于 PDF。

“注解将一个对象（如笔记、声音或电影）与 PDF 文档页面上的某个位置关联，或提供通过鼠标和键盘与用户互动的方式。”

注解与其页面之间存在父子关系。如果页面对象变得不可用（文档关闭、任何文档结构更改等），则其所有现有注解对象也变得不可用——每当访问注解属性或方法时，都会引发异常，提示对象“孤立”。

属性	简要描述
`Annot.delete_responses()`	删除所有响应注解
`Annot.get_file()`	获取附件内容
`Annot.get_oc()`	获取 `xref` of an `OCG` / `OCMD`
`Annot.get_pixmap()`	注解的图像 as a pixmap
`Annot.get_sound()`	获取音频注解的声音
`Annot.get_text()`	提取注解文本
`Annot.get_textbox()`	提取注解文本
`Annot.get_textpage()`	为注解创建 TextPage
`Annot.set_border()`	设置注解的边框属性
`Annot.set_blendmode()`	设置注解的混合模式
`Annot.set_colors()`	设置注解的颜色
`Annot.set_flags()`	设置注解的 flags 字段
`Annot.set_irt_xref()`	定义注解为“响应”于
`Annot.set_name()`	设置注解的 name 字段
`Annot.set_oc()`	设置 `xref` to an `OCG` / `OCMD`
`Annot.set_opacity()`	更改透明度
`Annot.set_open()`	打开 / 关闭注解或其 Popup
`Annot.set_popup()`	为注解创建 Popup
`Annot.set_rect()`	更改注解矩形
`Annot.set_rotation()`	更改旋转角度
`Annot.update_file()`	更新附件内容
`Annot.update()`	应用累积的注解更改
`Annot.blendmode`	注解 BlendMode
`Annot.border`	边框详情
`Annot.colors`	边框 / 背景和填充颜色
`Annot.file_info`	获取附件信息
`Annot.flags`	注解 flags
`Annot.has_popup`	注解是否带有 Popup
`Annot.irt_xref`	此注解响应的注解
`Annot.info`	各种信息
`Annot.is_open`	注解或其 Popup 是否打开
`Annot.line_ends`	线条类型注解的起点 / 终点外观
`Annot.next`	指向下一个注解的链接
`Annot.opacity`	注解的透明度
`Annot.parent`	注解的 page object
`Annot.popup_rect`	注解的 Popup 的矩形
`Annot.popup_xref`	注解的 Popup 的 PDF `xref` 编号
`Annot.rect`	包含注解的矩形
`Annot.type`	注解的类型
`Annot.vertices`	Polygons、PolyLines 等的点坐标
`Annot.xref`	PDF `xref` 编号

Class API

class Annot#

get_pixmap(matrix=pymupdf.Identity, dpi=None, colorspace=pymupdf.csRGB, alpha=False)#

v1.19.2 中的变更：添加了对 dpi 参数的支持。

从注解创建 pixmap，其外观与页面上未变换坐标系中的相同。该 pixmap 的 IRect 等于 Annot.rect.irect (见下文)。所有参数均为 keyword-only。

参数:

matrix (matrix_like) – 用于图像创建的矩阵。默认为 Identity。
dpi (int) – (v1.19.2 新增) 所需分辨率，单位为每英寸点数。如果不是 None，则 matrix 参数将被忽略。
colorspace (Colorspace) – 用于图像创建的颜色空间。默认为 pymupdf.csRGB。
alpha (bool) – 是否包含透明度信息。默认为 False。

返回类型:

Pixmap

注意

如果注解刚刚创建或修改，您应该首先通过 page = doc.reload_page(page) 来 Document.reload_page() 该页面。
如果 alpha=True，pixmap 将具有 “premultiplied” 像素。要了解一些背景信息，例如查找 “Premultiplied alpha” 在此在线术语表中。

get_text(opt, clip=None, flags=None)#

1.18.0 新增

以各种格式检索注解内容——与 Page 的同名方法非常相似。目前这仅为注解类型 ‘FreeText’ 和 ‘Stamp’ 提供相关数据。其他类型返回空字符串（或等效对象）。

参数:

opt (str) –
(positional only) 所需格式 - 以下值之一。请注意，此方法的行为与 Page 的同名方法完全相同。
- ”text” – TextPage.extractTEXT()，默认
- ”blocks” – TextPage.extractBLOCKS()
- ”words” – TextPage.extractWORDS()
- ”html” – TextPage.extractHTML()
- ”xhtml” – TextPage.extractXHTML()
- ”xml” – TextPage.extractXML()
- ”dict” – TextPage.extractDICT()
- ”json” – TextPage.extractJSON()
- ”rawdict” – TextPage.extractRAWDICT()
clip (rect-like) – (keyword only) 将提取限制在此区域。很少需要，默认为 Annot.rect。
flags (int) – (keyword only) 控制返回的数据量。默认为简单的文本提取。

get_textbox(rect)#

1.18.0 新增

返回注解文本。大部分内容（换行符除外）与选项设置为“text”的 Annot.get_text() 相同。

参数:: rect (rect-like) – 要考虑的区域，默认为 Annot.rect。

get_textpage(clip=None, flags=3)#

为注解创建 TextPage。

参数:

flags (int) – 控制后续文本提取和搜索可用内容的指示位——参见 Annot.get_text() 的参数。
clip (rect-like) – 将提取的文本限制在此区域。

返回:

TextPage

显示/隐藏历史

v1.25.5：修复了 clip 参数。

set_info(info=None, content=None, title=None, creationDate=None, modDate=None, subject=None)#

版本 1.16.10 中更改

更改注解属性。这些包括日期、内容、主题和作者（title）。对 name 和 id 的更改将被忽略。更新是选择性的：要使属性保持不变，将其设置为 None。要删除现有数据，使用空字符串。

参数:

info (dict) – 一个与 info 属性兼容的字典（见下文）。所有条目必须是字符串。如果此参数不是字典，则使用其他参数——否则将忽略它们。
content (str) – (v1.16.10 新增) 参见 info 中的描述。
title (str) – (v1.16.10 新增) 参见 info 中的描述。
creationDate (str) – (v1.16.10 新增) 注解创建日期。如果提供，应为 PDF 日期时间格式。
modDate (str) – (v1.16.10 新增) 最后修改日期。如果提供，应为 PDF 日期时间格式。
subject (str) – (v1.16.10 新增) 参见 info 中的描述。

set_line_ends(start, end)#

设置注解的线条末端样式。每种这些注解类型都由一系列点定义，这些点由线条连接。由 start 标识的符号附加到列表的第一个点，而 end 附加到列表的最后一个点。对于不支持的注解类型，将产生无操作并带有警告消息。

注意

一些符号有内部区域（菱形、圆形、方形等）。这些区域将填充填充颜色或描边颜色，具体取决于注解类型。

参数:

start (int) – 第一个点的符号编号。
end (int) – 最后一个点的符号编号。

set_oc(xref)#

使用 PDF 可选内容机制设置注解的可见性。此可见性由支持的 PDF 查看器的用户界面控制。它独立于其他属性，如 Annot.flags。

参数:: xref (int) – 可选内容组 (OCG 或 OCMD) 的 xref。任何先前的 xref 将被覆盖。如果为零，则将删除先前的条目。如果 xref 不为零且不指向有效的 PDF 对象，则会发生异常。

注意

这无需执行 Annot.update() 即可生效。

get_oc()#

返回可选内容对象的 xref，如果没有则返回零。

返回:: 零或 OCG (或 OCMD) 的 xref。

set_irt_xref(xref)#

v1.19.3 新增

设置注解为“响应”于另一个注解。

参数:

xref (int) –

另一个注解的 xref。

注意

必须引用此页面上存在的注解。设置此属性无需后续执行 update()。

set_open(value)#

v1.18.4 新增

设置注解的 Popup 注解为打开或关闭——或注解本身，如果其类型为 ‘Text’（“便签”）。

参数:: value (bool) – 所需的打开状态。

set_popup(rect)#

v1.18.4 新增

为注解创建一个 Popup 注解并指定其矩形。如果 Popup 已存在，则仅更新其矩形。

参数:: rect (rect_like) – 所需矩形。

set_opacity(value)#

设置注解的透明度。透明度也可以在 Annot.update() 中设置。

参数:: value (float) – 范围 [0, 1] 内的浮点数。任何超出范围的值都将被视为 1。例如，值 0.5 将透明度设置为 50%。

三个重叠的‘Circle’注解，每个透明度设置为 0.5

blendmode#

v1.18.4 新增

注解的混合模式。有关说明，请参阅 Adobe PDF Reference 第 324 页。

返回类型:: str
返回:: 混合模式或 None。

set_blendmode(blendmode)#

v1.16.14 新增

设置注解的混合模式。有关说明，请参阅 Adobe PDF Reference 第 324 页。混合模式也可以在 Annot.update() 中设置。

参数:: blendmode (str) – 设置混合模式。使用 Annot.update() 在视觉外观上反映此更改。有关预定义值，请参阅 PDF 标准混合模式。使用 PDF_BM_Normal 删除混合模式。

set_name(name)#

版本 1.16.0 新增

更改任何注解类型的名称字段。对于‘FileAttachment’和‘Text’注解，这是图标名称；对于‘Stamp’注解，这是图章中的文本。视觉结果（如果有）取决于您的 PDF 查看器。另请参阅 MuPDF 中的注解图标。

参数:: name (str) – 新名称。

注意

如果您设置‘Stamp’注解的名称，则这不会更改矩形，也不会以任何方式布局文本。如果您从图章注解图标中选择标准文本（"STAMP_" 之后的精确名称部分），您应该获得原始布局。任意文本不会更改为大写，而是按原样以字体“Times-Bold”写入，在一行中水平居中并缩短以适应。要完全显示您的文本，使用 fontsize 20 时其长度不得超过 190 点。因此，请确保以下不等式为真：pymupdf.get_text_length(text, fontname="tibo", fontsize=20) <= 190。

set_rect(rect)#

更改注解的矩形。注解可以移动，矩形的两侧可以独立缩放。然而，注解外观永远不会旋转、翻转或倾斜。此方法仅影响某些注解类型[2]，在其他情况下会导致 Python 的 sys.stderr 上出现消息。不会引发异常，但将返回 False。

参数:: rect (rect_like) – 注解的新矩形（有限且非空）。例如，使用值 annot.rect + (5, 5, 5, 5) 将把注解位置向右和向下移动 5 像素。

注意

您无需调用 Annot.update() 来激活效果。

set_rotation(angle)#

设置注解的旋转角度。这将围绕其中心点旋转注解矩形。然后从生成的 quad 计算新的注解矩形。

参数:: angle (int) – 旋转角度，单位为度。任意值均可，但将被限制在区间 [0, 360) 内。

注意

您必须调用 Annot.update() 来激活效果。
对于 PDF_ANNOT_FREE_TEXT，仅可能值为 0、90、180 和 270，这将旋转当前矩形（保持不变）内的文本。其他值将被静默忽略并替换为 0。
否则，只有以下注解类型可以旋转：‘Square’、‘Circle’、‘Caret’、‘Text’、‘FileAttachment’、‘Ink’、‘Line’、‘Polyline’、‘Polygon’ 和 ‘Stamp’。对于所有其他类型，此方法无效。

set_border(border=None, width=None, style=None, dashes=None, clouds=None)#

版本 1.16.9 中更改：允许不使用字典进行指定。如果 border 不是字典，则使用直接参数。
版本 1.22.5 中更改：支持“云状”边框效果。

仅限 PDF：更改边框宽度、虚线样式、样式和云状效果。有关更多详细信息，请参见 Annot.border 属性。

参数:

border (dict) – 一个字典，与 border 属性返回的字典兼容，包含键 “width” (float)、 “style” (str)、 “dashes” (sequence) 和 clouds (int)。省略的键将使相应属性保持不变。将 border 参数设置为 None (默认值) 以使用其他参数。
width (float) – 非负值将更改边框线宽。
style (str) – 非 None 的值将更改此边框属性。
dashes (sequence) – 序列的所有项必须是整数，否则该参数将被忽略。要移除虚线，请使用：dashes=[]。如果 dashes 是非空序列，“style”将自动设置为“D”（虚线）。
clouds (int) – 大于等于 0 的值将更改此属性。使用 clouds=0 可完全移除云状外观。此属性仅支持注解类型 ‘Square’、‘Circle’ 和 ‘Polygon’。

set_flags(flags)#

更改注解 flags。使用 | 运算符组合多个 flags。

参数:: flags (int) – 指定所需 flags 的整数。

set_colors(colors=None, stroke=None, fill=None)#

更改受支持注解类型的“描边”和“填充”颜色——并非所有注解类型都接受两者。对于 FreeText 注解完全不要使用此方法，因为它有特殊的约定来处理最多三种颜色（边框、填充、文本）。

参数:

colors (dict) – 包含颜色规格的字典。有关接受的字典键和值，请参见下文。最实用的方法应该是先复制 colors 属性，然后根据需要修改此字典。
stroke (sequence) – 见上文。
fill (sequence) – 见上文。

要完全移除颜色规格，请使用空序列，如 []。如果指定 None，现有规格将不会更改。

delete_responses()#

版本 1.16.12 新增

删除引用此注解的注解。这包括任何‘Popup’注解和所有响应于此注解的注解。

update(opacity=None, blend_mode=None, fontsize=0, text_color=None, border_color=None, fill_color=None, cross_out=True, rotate=-1)#

在相关更改后，同步注解外观与其属性。

您仅在以下更改时可以安全地省略此方法

Annot.set_rect()

Annot.set_flags()

Annot.set_oc()

Annot.update_file()

Annot.set_info() （除对 “content” 的任何更改外）

所有参数都是可选的。(v1.16.14 中更改) 混合模式和透明度适用于所有注解类型。其他参数主要用于特殊情况，如下所述。

颜色规格可以使用 PuMuPDF 中常用的格式给出，即由范围在 0.0 到 1.0（包含两者）之间的浮点数组成的序列。序列长度必须为 1、3 或 4（分别支持 GRAY、RGB 和 CMYK 颜色空间）。对于 GRAY，也可以只用一个浮点数。

参数:

opacity (float) – (v1.16.14 新增) 适用于所有注解类型：更改或设置注解的透明度。有效值为 0 <= opacity < 1。
blend_mode (str) – (v1.16.14 新增) 适用于所有注解类型：更改或设置注解的混合模式。有效值请参见 PDF 标准混合模式。
fontsize (float) – 更改文本的 fontsize。仅限‘FreeText’注解。
text_color (sequence,float) – 更改文本颜色。仅限‘FreeText’注解。这与 border_color 效果相同。请注意，富文本注解的文本颜色根本无法更改，因为它由 HTML / CSS 语法设置并作为文本本身的一部分。
border_color (sequence,float) – 更改边框颜色。仅限‘FreeText’注解。这与 text_color 效果相同。
fill_color (sequence,float) – 填充颜色。
cross_out (bool) – (v1.17.2 新增) 在注解矩形中添加两条对角线。仅限‘Redact’注解。如果不需要，即使注解创建时设置为 False，也必须指定 False。
rotate (int) – 新的旋转值。默认值 (-1) 表示不更改。支持‘FreeText’和几种其他注解类型（参见 Annot.set_rotation()）[1]。对于‘FreeText’，只选择 0、90、180 或 270 度。否则，任何整数都可以接受。

返回类型:

bool

此方法是更改 FreeText 注解颜色的唯一方法。您不能为此目的使用 Annot.set_colors()。但请注意，对于富文本注解，文本颜色永远不会更改。文本颜色由 info 字典的 text_color 条目设置。这是 MuPDF 的限制，而不是 bug。

注意

不建议在 Page.annots() 循环内使用此方法！这是因为大多数注解更新需要重新加载所属页面——这在此循环内无法完成。请使用此生成器文档中给出的示例编码模式。

file_info#

注解附件的基本信息。

返回类型:: dict
返回:: 一个字典，对于 FileAttachment 注解类型包含键 filename、 ufilename、 desc (描述)、 size (未压缩文件大小)、 length (压缩长度)，否则为 None。

get_file()#

返回附件内容。

返回类型:: bytes
返回:: 附件的内容。

update_file(buffer=None, filename=None, ufilename=None, desc=None)#

更新附件内容。所有参数都是可选的。不带参数会导致无操作。

参数:

buffer (bytes|bytearray|BytesIO) –
新的文件内容。省略此参数仅更改元信息。

(版本 1.14.13 中更改) 现在也支持 io.BytesIO。
filename (str) – 与文件关联的新文件名。
ufilename (str) – 与文件关联的新 unicode 文件名。
desc (str) – 文件内容的新描述。

get_sound()#

返回音频注解中嵌入的声音。

返回类型:

dict

返回:

声音音频文件及附带属性。这些是可能的字典键，其中只有“rate”和“stream”总是存在。

键	描述
rate	(float, requ.) 每秒样本数
channels	(int, opt.) 声道数
bps	(int, opt.) 每通道每样本值位数
encoding	(str, opt.) 编码格式：Raw, Signed, muLaw, ALaw
compression	(str, opt.) 压缩过滤器名称
stream	(bytes, requ.) 音频文件内容

opacity#

注解的透明度。如果已设置，则为范围 [0, 1] 内的值。PDF 默认值为 1。但是，为了区分，如果未设置，我们将返回 -1.0。

返回类型:: float

parent#

注解所属的 page object。

返回类型:: Page

rotation#

注解的旋转角度。

返回类型:: int
返回:: 值在 [-1, 359] 范围内。如果完全没有旋转，返回 -1（意味着旋转角度为 0）。其他可能值归一化为 0 <= angle < 360 的某个值。

rect#

包含注解的矩形。

返回类型:: Rect

next#

此页面上的下一个注解或 None。

返回类型:: Annot

type#

描述注解类型的编号和一个或两个字符串，例如 [2, ‘FreeText’, ‘FreeTextCallout’]。第二个字符串条目是可选的，可能为空。有关可能值及其含义的列表，请参阅附录注解类型。

返回类型:: list

info#

包含各种信息的字典。所有字段都是可选的字符串。对于未提供的信息项，返回空字符串。

name – 例如，对于‘Stamp’注解，它将包含图章文本，如“Sold”或“Experimental”；对于其他注解类型，您将在此处看到注解图标的名称（FileAttachment 为“PushPin”）。
content – 对于类型为 Text 和 FreeText 的注解，包含文本的字符串。通常用于填充注解弹出窗口的文本字段。
title – 包含注解弹出窗口标题的字符串。根据约定，这用于表示注解作者。
creationDate – 创建时间戳。
modDate – 最后修改时间戳。
subject – 主题。
id – (版本 1.16.10 新增) 注解的唯一标识。取自 PDF 键 /NM。PyMuPDF 添加的注解将具有唯一的名称，在此处显示。

返回类型:: dict

flags#

一个整数，其低位包含有关如何呈现注解的标志。

返回类型:: int

line_ends#

一个整数对，指定注解类型‘FreeText’、‘Line’、‘PolyLine’和‘Polygon’的起点和终点符号。如果适用，则为 None。此列表中可能的值和描述，请参阅 Adobe PDF Reference 第 400 页表 1.76。

返回类型:: tuple

vertices#

一个列表，包含可变数量的点（“顶点”）坐标（每个由一对浮点数给出），适用于各种类型的注解

‘Line’ – 起点和终点坐标（2 对浮点数）。
‘FreeText’ – 2 或 3 对浮点数，指定起点、可选的膝盖点和终点坐标。
‘PolyLine’ / ‘Polygon’ – 由线段连接的边缘的坐标（n 个点对应 n 对浮点数）。
文本标记注解 – 4 对浮点数，指定标记文本范围的 QuadPoints（参见 Adobe PDF Reference 第 403 页）。
‘Ink’ – 包含一个或多个子列表的顶点坐标列表。每个这样的子列表代表绘图中的一条单独线条。

返回类型:: list

colors#

包含两个浮点数列表（范围为 0 <= float <= 1）的字典，指定“描边”和内部（“填充”）颜色。描边颜色用于边框和所有主动绘制或书写的内容（“描边”）。填充颜色用于线条末端、圆形和方形等对象的内部。这些列表的长度隐含地确定了使用的颜色空间：1 = GRAY，3 = RGB，4 = CMYK。因此，“[1.0, 0.0, 0.0]”代表 RGB 颜色红色。如果未指定颜色，两个列表都可以为空。请注意一些潜在的意外情况

高亮注解的颜色是描边颜色，这与直觉相反。
FreeText 注解的颜色是描边颜色，但显示为填充矩形和任何适用线条末端符号的颜色。文本颜色和边框颜色根本无法访问。

返回类型:: dict

xref#

PDF xref。

返回类型:: int

irt_xref#

此注解所响应的注解的 PDF xref。如果这不是响应注解，则返回零。

返回类型:: int

popup_xref#

关联 Popup 注解的 PDF xref。如果不存在，则为零。

返回类型:: int

has_popup#

注解是否带有 Popup 注解。

返回类型:: bool

is_open#

注解的 Popup 是否打开——或注解本身（仅限‘Text’注解）。

返回类型:: bool

popup_rect#

关联 Popup 注解的矩形。如果不存在，则为无限矩形。

返回类型:: Rect

rect_delta#: 一个包含四个浮点数的元组，表示注解的 /RD 条目。这四个数字描述了两个矩形之间的数值差异（左、上、-右、-下）：注解的 rect 和包含在该矩形内的另一个矩形。如果该条目缺失，此属性为 (0, 0, 0, 0)。如果注解边框是正常的直线，这些数字通常是边框宽度除以 2。如果注解有“云状”边框，您将在此处看到云状半圆的宽度。通常，这些数字不必相同。要计算内部矩形，请执行 a.rect + a.rect_delta。

border#

包含边框特征的字典。如果不存在边框信息，则为空。可能存在以下键

width – 一个浮点数，表示边框厚度，单位为点。如果未指定宽度，则值为 -1.0。
dashes – 指定线条虚线模式的整数序列。[] 表示无虚线，[n] 表示相等长度的开启-关闭虚线，每段长 n 点，更长的列表将被解释为指定交替的开启-关闭长度值。更多详细信息请参阅 Adobe PDF Reference 第 126 页。
style – 1 字节边框样式：“S” (Solid) = 围绕注解的实线，“D” (Dashed) = 围绕注解的虚线，虚线模式由 dashes 条目指定，“B” (Beveled) = 模拟的浮雕矩形，看起来高于页面表面，“I” (Inset) = 模拟的凹陷矩形，看起来低于页面表面，“U” (Underline) = 沿注解矩形底部的一条单线。
clouds – 一个整数，表示“云状”边框，其中 n 是一个整数，满足 -1 <= n <= 2。值 n = 0 表示直线（无云状），1 表示小半圆，2 表示大半圆，模拟云状外观。如果为 -1，则表示没有规格。

返回类型:: dict

MuPDF 中的注解图标#

这是一个列表，列出了注解类型‘Text’和‘FileAttachment’可以按名称引用的图标。您可以在添加注解时通过 icon 参数使用它们，或在 Annot.set_name() 中作为参数使用。选择哪个项目取决于您——没有机制会阻止您例如将“Speaker”图标用于‘FileAttachment’。

示例#

更改注解的图形图像。同时更新“author”和在弹出窗口中显示的文本

doc = pymupdf.open("circle-in.pdf")
page = doc[0]                          # page 0
annot = page.first_annot                # get the annotation
annot.set_border(dashes=[3])           # set dashes to "3 on, 3 off ..."

# set stroke and fill color to some blue
annot.set_colors({"stroke":(0, 0, 1), "fill":(0.75, 0.8, 0.95)})
info = annot.info                      # get info dict
info["title"] = "Jorj X. McKie"        # set author

# text in popup window ...
info["content"] = "I changed border and colors and enlarged the image by 20%."
info["subject"] = "Demonstration of PyMuPDF"     # some PDF viewers also show this
annot.set_info(info)                   # update info dict
r = annot.rect                         # take annot rect
r.x1 = r.x0 + r.width  * 1.2           # new location has same top-left
r.y1 = r.y0 + r.height * 1.2           # but 20% longer sides
annot.set_rect(r)                      # update rectangle
annot.update()                         # update the annot's appearance
doc.save("circle-out.pdf")             # save

更改前后的圆形注解外观如下（使用 Nitro PDF 查看器显示的弹出窗口）

circle

脚注

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