注释#
引用来自 Adobe PDF References：“注释将对象（例如注释、声音或电影）与 PDF 文档页面上的位置关联，或者通过鼠标和键盘提供与用户交互的方式。”
注释与其页面之间存在父子关系。如果页面对象变得不可用（关闭文档、任何文档结构更改等），那么它的所有现有注释对象也会如此 - 每当访问注释属性或方法时，会抛出一个异常，说明该对象是“孤立的”。
属性 |
简短描述 |
|---|---|
删除所有响应的注释 |
|
获取附加文件内容 |
|
注释的图像作为位图 |
|
获取音频注释的声音 |
|
提取注释文本 |
|
提取注释文本 |
|
设置注释的边框属性 |
|
设置注释的混合模式 |
|
设置注释的颜色 |
|
设置注释的标志字段 |
|
定义注释为“响应于” |
|
设置注释的名称字段 |
|
改变透明度 |
|
打开/关闭注释或其弹出窗口 |
|
为注释创建一个弹出窗口 |
|
更改注释矩形 |
|
改变旋转 |
|
更新附件文件内容 |
|
应用累积的注释更改 |
|
注释混合模式 |
|
边框详情 |
|
边框/背景和填充颜色 |
|
获取附加文件信息 |
|
注释标志 |
|
注释是否有弹出框 |
|
此注释所响应的注释 |
|
各种信息 |
|
是否注释或其弹出窗口已打开 |
|
线型注释的开始/结束外观 |
|
链接到下一个注释 |
|
注释的透明度 |
|
注释的页面对象 |
|
注释弹出框的矩形 |
|
注释弹出窗口的PDF |
|
包含注释的矩形 |
|
注释的类型 |
|
多边形、折线等的点坐标。 |
|
PDF |
类 API
- class Annot#
- get_pixmap(matrix=pymupdf.Identity, dpi=None, colorspace=pymupdf.csRGB, alpha=False)#
在 v1.19.2 中更改：添加了 dpi 参数的支持。
从注释创建一个位图，注释在页面上以未转换的坐标出现。位图的 IRect 等于 Annot.rect.irect（见下文）。 所有参数仅为关键字。
- Parameters:
matrix (matrix_like) – 用于图像创建的矩阵。默认值是 Identity。
dpi (int) – （在 v1.19.2 中新增）所需的每英寸点数的分辨率。如果不是
None，则忽略矩阵参数。colorspace (Colorspace) – 用于图像创建的颜色空间。默认是 pymupdf.csRGB。
alpha (bool) – 是否包含透明度信息。默认为 False。
- Return type:
注意
如果注释刚刚被创建或修改，你应该首先通过
page = doc.reload_page(page)Document.reload_page()页面。如果
alpha=True，则位图将具有 “预乘” 像素。要了解一些背景，例如，可以在 这里 查找“预乘 alpha”。
- get_text(opt, clip=None, flags=None)#
1.18.0 新特性
以多种格式检索注释的内容——就像Page的相同方法。这目前仅为‘FreeText’和‘Stamp’类型的注释提供相关数据。其他类型返回空字符串（或等效对象）。
- Parameters:
opt (str) –
(仅限位置参数) 所需的格式 - 以下值之一。请注意，此方法的工作方式与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 (矩形区域) – （仅限关键字）将提取限制在此区域。几乎不需要，默认值为
Annot.rect。flags (int) – （仅限关键字）控制返回的数据量。默认为简单文本提取。
- get_textbox(rect)#
1.18.0 新特性
返回注释文本。大多数情况下（除了换行符）等于
Annot.get_text()的“文本”选项。- Parameters:
rect (矩形状) – 要考虑的区域，默认为
Annot.rect。
- set_info(info=None, content=None, title=None, creationDate=None, modDate=None, subject=None)#
在版本 1.16.10 中更改
更改注释属性。这些包括日期、内容、主题和作者（标题）。对name和id的更改将被忽略。更新是选择性的：要保持属性不变，请将其设置为None。要删除现有数据，请使用空字符串。
- Parameters:
信息 (字典) – 与 信息 属性兼容的字典（见下文）。所有条目必须是字符串。如果此参数不是字典，则使用其他参数 – 否则它们被忽略。
内容 (str) – (v1.16.10 新增) 请参见
info中的说明。标题 (字符串) – (在 v1.16.10 中新增) 请参见
info中的描述。creationDate (str) – (在 v1.16.10 新增) 注释创建的日期。如果给出，应该采用 PDF 日期时间格式。
modDate (str) – (在 v1.16.10 中新增) 最后修改的日期。如果提供，应该是 PDF 日期时间格式。
主题 (字符串) – (在v1.16.10中新增) 请参见
info中的描述。
- set_line_ends(start, end)#
设置注释的线条结束样式。这些注释类型是由一系列相连的点定义的。start标识的符号附加在第一个点上，end附加在这一系列的最后一个点上。对于不支持的注释类型，将产生无操作和警告信息。
注意
虽然'FreeText'、'Line'、'PolyLine'和'Polygon'注释可以具有这些属性，（Py-）MuPDF不支持'FreeText'的线条结尾，因为它的标注变体不受支持。
(v1.16.16中更改) 一些符号有内部区域（菱形、圆形、方形等）。默认情况下，这些区域填充注释的填充颜色。如果为None，则选择白色。fill_color参数的
Annot.update()现在可以用来覆盖这个设置，并为线条结束符号赋予自己的填充颜色。
- Parameters:
start (int) – 第一个点的符号编号。
end (int) – 最后一个点的符号编号。
- set_oc(xref)#
使用PDF可选内容机制设置注释的可见性。此可见性由支持PDF查看器的用户界面控制。它与其他属性无关，如
Annot.flags。- Parameters:
xref (int) – 可选内容组 (OCG 或 OCMD) 的
xref。任何之前的 xref 将被覆盖。如果为零，之前的条目将被移除。如果 xref 不是零且不指向有效的 PDF 对象，则会发生异常。
注意
这不需要执行
Annot.update()才能生效。
- set_irt_xref(xref)#
v1.19.3中的新功能
将注释设置为“响应于”另一个。
- set_open(value)#
v1.18.4的新特性
设置注释的弹出注释为打开或关闭 - 或者 注释本身，如果它的类型是“文本”（“便签”）。
- Parameters:
value (bool) – 所需的打开状态。
- set_popup(rect)#
v1.18.4 中的新功能
为注释创建一个弹出注释并指定其矩形。如果弹出窗口已经存在，则仅更新其矩形。
- Parameters:
rect (rect_like) – 期望的矩形。
- set_opacity(value)#
设置注释的透明度。透明度也可以在
Annot.update()中设置。- Parameters:
值 (浮点数) – 范围在 [0, 1] 之间的浮点数。任何超出此范围的值均视为 1。例如，值为 0.5 可将透明度设置为 50%。
三个重叠的“圆”注释，各自的不透明度设置为0.5：
- blendmode#
v1.18.4的新特性
注释的混合模式。请参见 Adobe PDF References，第 324 页以获取解释。
- Return type:
字符串
- Returns:
混合模式或 None。
- set_blendmode(blendmode)#
v1.16.14的新特性
设置注释的混合模式。参见Adobe PDF 参考，第324页以获取说明。混合模式也可以在
Annot.update()中设置。- Parameters:
混合模式 (字符串) – 设置混合模式。使用
Annot.update()来反映这一点在视觉外观中。有关预定义值，请参见 PDF标准混合模式。使用PDF_BM_Normal来 移除 混合模式。
- set_name(name)#
版本 1.16.0 中的新功能
更改任何注释类型的名称字段。对于‘FileAttachment’和‘Text’注释，这是图标名称，对于‘Stamp’注释，是印章中的文本。视觉结果（如果有的话）取决于您的PDF查看器。另见MuPDF中的注释图标。
- Parameters:
name (str) – 新名称。
注意
如果您设置“Stamp”注释的名称，则这将不会改变矩形，也不会以任何方式布局文本。如果您选择来自 Stamp Annotation Icons 的标准文本（确切的名称部分在
"STAMP_"之后），您应该会收到原始布局。任意文本将不会被转换为大写，而是以“Times-Bold”字体原样书写，水平居中在一行中并被缩短以适应。为了使您的文本完全显示，它的长度使用fontsize20 不能超过 190 点。因此，请确保以下不等式成立：pymupdf.get_text_length(text, fontname="tibo", fontsize=20) <= 190。
- set_rect(rect)#
更改注释的矩形。注释可以移动，并且矩形的两侧可以独立缩放。然而，注释的外观永远不会被旋转、翻转或倾斜。此方法仅影响某些注释类型 [2]，在其他情况下会导致Python的
sys.stderr上出现一条消息。不会引发异常，但会返回False。- Parameters:
rect (rect_like) – 注释的新矩形（有限且非空）。例如，使用值 annot.rect + (5, 5, 5, 5) 将把注释位置向右和向下移动5个像素。
注意
您 无需 调用
Annot.update()来激活效果。
- set_rotation(angle)#
设置注释的旋转。这会围绕其中心点旋转注释矩形。然后从结果四边形计算出一个新的注释矩形。
- Parameters:
angle (int) – 旋转角度（度）。可以使用任意值，但将被限制在区间
[0, 360)内。
注意
您 必须调用
Annot.update()以激活效果。对于 PDF_ANNOT_FREE_TEXT，仅有值 0、90、180 和 270 之一是可能的，并将 旋转文本 在当前矩形内部（该矩形保持不变）。其他值将被静默忽略并替换为 0。
否则，只有以下 注释类型 可以旋转：‘方形’，‘圆形’，‘插入符号’，‘文本’，‘文件附件’，‘墨水’，‘线’，‘折线’，‘多边形’，和 ‘印章’。对于其他所有类型，该方法无效。
- set_border(border=None, width=None, style=None, dashes=None, clouds=None)#
在版本 1.16.9 中更改：允许在不使用字典的情况下指定。 如果 border 不是字典，则使用直接参数。
在版本 1.22.5 中更改：支持“阴 cloudy” 边框效果。
仅限PDF：改变边框宽度、虚线、样式和云效果。有关更多详细信息，请参见
Annot.border属性。- Parameters:
边框 (字典) – 由
border属性返回的字典，包含键“宽度” (浮动), “样式” (字符串), “虚线” (序列) 和 云 (整数)。省略的键将保持相应属性不变。将边框参数设置为None（默认值）以使用其他参数。width (float) – 一个非负值将改变边框线宽度。
样式 (字符串) – 除了
无以外的值将改变此边框属性。虚线 (序列) – 序列中的所有项必须是整数，否则该参数将被忽略。要取消虚线效果，请使用:
dashes=[]。如果虚线是非空序列，“style”将自动设置为“D”（虚线）。云 (整型) – 一个值 >= 0 将改变此属性。使用
clouds=0完全去除多云外观。只有注释类型 ‘正方形’，‘圆形’ 和 ‘多边形’ 支持此属性。
- set_flags(flags)#
更改注释标志。使用
|运算符来组合多个。- Parameters:
flags (int) – 指定所需标志的整数。
- set_colors(colors=None, stroke=None, fill=None)#
在版本 1.16.9 中更改：允许直接设置颜色。如果 colors 不是字典，则使用这些参数。
更改支持的注释类型的“描边”和“填充”颜色 - 并非所有注释都接受两者。
- Parameters:
colors (dict) – 一个包含色彩规范的字典。有关接受的字典键和值，请参见下方。最实用的方法应该是先复制 colors 属性，然后根据需要修改此字典。
stroke (sequence) – 请参见上文。
填充 (序列) – 见上文。
在v1.18.5中更改： 要完全移除颜色规范，请使用一个空序列，如
[]。如果您指定None，现有规范将不会被更改。
- delete_responses()#
在版本 1.16.12 中的新功能
删除指向此注释的注释。这包括任何“弹出”注释以及所有响应此注释的注释。
- update(opacity=None, blend_mode=None, fontsize=0, text_color=None, border_color=None, fill_color=None, cross_out=True, rotate=-1)#
在相关更改后，同步注释的外观与其属性。
您可以安全地 省略 此方法 仅仅 适用于以下更改：
Annot.set_info()（除了对 “content” 的任何更改）
所有参数都是可选的。 (在v1.16.14中更改) 混合模式和不透明度适用于 所有注释类型。 其他参数主要是特殊用途，如下所述。
颜色规格可以按照PuMuPDF中使用的常见格式进行说明，使用范围从0.0到1.0的浮点数序列（包括这两个值）。序列长度必须为1、3或4（分别支持GRAY、RGB和CMYK颜色空间）。对于GRAY，仅一个浮点数也是可以接受的。
- Parameters:
不透明度 (浮点数) – (在v1.16.14中新增加) 适用于所有注释类型：改变或设置注释的透明度。有效值为 0 <= 不透明度 < 1。
blend_mode (str) – (v1.16.14新功能) 适用于所有注释类型：更改或设置注释的混合模式。有效值请参见 PDF标准混合模式。
fontsize (float) – 改变
fontsize的文本大小。仅适用于‘FreeText’注释。text_color (sequence,float) – 改变文本颜色。仅适用于“FreeText”注释。
border_color (sequence,float) – 更改边框颜色。仅适用于“自由文本”注释。
fill_color (sequence,float) –
填充颜色。
’Line’, ‘Polyline’, ‘Polygon’ 注释：用它为适用的线尾符号提供填充颜色，而不是注释的颜色 (changed in v1.16.16)。
cross_out (bool) – (在 v1.17.2 中新增) 在注释矩形上添加两条对角线。仅适用于‘Redact’注释。如果不需要，必须指定 False，即使注释是使用 False 创建的。
rotate (int) – 新的旋转值。默认值 (-1) 表示不变。支持‘FreeText’和其他几种注释类型（见
Annot.set_rotation()），[1]。对于‘FreeText’，只能选择 0、90、180 或 270 度。否则任何整数都是可以接受的。
- Return type:
布尔值
注意
在
Page.annots()循环中使用此方法不推荐!这是因为大多数注释更新需要重新加载拥有该注释的页面 - 这在此循环内无法完成。请使用本生成器文档中提供的示例编码模式。
- file_info#
附加文件的基本信息。
- Return type:
字典
- Returns:
一个字典，包含键 filename、ufilename、desc（描述）、size（未压缩文件大小）、length（压缩长度），用于 FileAttachment 注释类型，否则为 None。
- get_file()#
返回附加文件内容。
- Return type:
字节
- Returns:
附加文件的内容。
- update_file(buffer=None, filename=None, ufilename=None, desc=None)#
更新附加文件的内容。所有参数都是可选的。没有参数将导致不执行任何操作。
- Parameters:
buffer (bytes|bytearray|BytesIO) –
新的文件内容。省略以仅更改元信息。
(在版本 1.14.13 中更改) io.BytesIO 现在也得到了支持。
filename (str) – 关联到文件的新文件名。
ufilename (str) – 与文件关联的新unicode文件名。
desc (str) – 文件内容的新描述。
- get_sound()#
返回音频注释的嵌入声音。
- Return type:
字典
- Returns:
声音音频文件及其相关属性。这些是可能的字典键，其中只有“rate”和“stream”始终存在。
键
描述
rate
(float, 必需) 每秒样本数
channels
(int, 可选) 声道数量
bps
(int, 可选) 每个声道每个样本值的位数
encoding
(str, 可选) 编码格式：Raw, Signed, muLaw, ALaw
compression
(str, 可选) 压缩过滤器名称
stream
(bytes, 必需) 声音文件内容
- opacity#
注释的透明度。如果设置，它的值范围为 [0, 1]。PDF 的默认值为 1。然而，为了区分，如果未设置，我们返回 -1.0。
- Return type:
浮点数
- rotation#
注释旋转。
- Return type:
整型
- Returns:
一个值 [-1, 359]。如果旋转完全不发生，则返回 -1（并意味着旋转角度为 0）。其他可能的值被规范化为某个值 0 <= angle < 360。
- next#
此页面上的下一个注释或无。
- Return type:
注释
- type#
一个数字和一个或两个描述注释类型的字符串，如 [2, ‘FreeText’, ‘FreeTextCallout’]。第二个字符串条目是可选的，可能为空。请参见附录 注释类型 以获取可能值及其含义的列表。
- Return type:
列表
- info#
一个包含各种信息的字典。所有字段都是可选字符串。对于未提供的信息项，将返回一个空字符串。
name – 例如，对于“印章”注释，它将包含印章文本，如“已售”或“实验性”，对于其他注释类型，您将在此处看到注释图标的名称（“PushPin”用于文件附件）。
content – 一个包含类型 Text 和 FreeText 注释文本的字符串。通常用于填写注释弹出窗口的文本字段。
标题 – 包含注释弹出窗口标题的字符串。按照惯例，这用于 注释作者。
creationDate – 创建时间戳。
modDate – 最后修改时间戳。
主题 – 主题。
id – (在版本 1.16.10 中新增加) 注释的唯一标识。这是从 PDF 键 /NM 中获取的。由 PyMuPDF 添加的注释将具有一个唯一名称，出现在这里。
- Return type:
字典
- flags#
一个整数，其低位包含用于指示注解应如何呈现的标志。
- Return type:
整型
- line_ends#
一对整数，指定注释类型‘FreeText’，‘Line’，‘PolyLine’，和‘Polygon’的起始和结束符号。如果不适用则无。有关该列表中可能值及其描述，请参见Adobe PDF References，第400页的表1.76。
- Return type:
元组
- vertices#
一个包含可变数量点（“顶点”）坐标的列表（每个由一对浮点数给出），用于各种类型的注释：
‘Line’ – 起始和结束坐标 (2 个浮点数对)。
‘FreeText’ - 2 或 3 个浮点数对，指定起始点、（可选的）转折点和结束坐标。
‘PolyLine’ / ‘Polygon’ – 边缘的坐标由线段连接（n个浮点数对表示n个点）。
文本标记注释 - 4 个浮点数对，指定标记文本范围的 QuadPoints (请参见 Adobe PDF References，第 403 页)。
‘Ink’ – 一系列一个到多个子列表的顶点坐标。每个子列表代表绘图中的一条独立线条。
- Return type:
列表
- colors#
一个包含两个浮点数列表的字典，范围为 0 <= float <= 1，指定“边框”和内部（“填充”）颜色。边框颜色用于边界以及所有被积极绘制或书写的内容（“边框绘制”）。填充颜色用于对象的内部，如线条末端、圆形和方形。这些列表的长度隐式地决定所使用的颜色空间：1 = 灰度，3 = RGB，4 = CMYK。因此“[1.0, 0.0, 0.0]”表示RGB颜色红色。如果未指定颜色，两个列表可以为空。
- Return type:
字典
- has_popup#
注释是否具有弹出注释。
- Return type:
布尔值
- is_open#
注释的弹出窗口是否打开 – 或者 注释本身（仅限“文本”注释）。
- Return type:
布尔值
- rect_delta#
一个由四个浮点数组成的元组，表示注释的
/RD条目。四个数字描述两个矩形之间的数值差异（左，上，-右，-下）：注释的rect和包含在该矩形内的矩形。如果条目缺失，则该属性为(0, 0, 0, 0)。如果注释边框是一条正常的直线，这些数字通常是边框宽度除以 2。如果注释有“云朵”边框，您会在这里看到云半圆的宽度。一般来说，这些数字不需要相同。要计算内部矩形，请执行a.rect + a.rect_delta。
- border#
一个包含边框特征的字典。如果没有边框信息，则为空。以下键可能存在：
width – 一个浮点数，表示边框的厚度，单位为点。如果未指定宽度，则值为 -1.0。
虚线 – 一系列整数，指定线条的虚线模式。 [] 表示没有虚线，[n] 表示 n 个点的等长开关，较长的列表将被解释为指定交替的开关长度值。有关更多细节，请参见 Adobe PDF References 第126页。
style – 1字节边框样式: “S” (实线) = 环绕注释的实线, “D” (虚线) = 环绕注释的虚线, 虚线模式由dashes条目指定, “B” (斜面) = 一个模拟的浮雕矩形，看起来凸出于页面表面, “I” (内嵌) = 一个模拟的凹刻矩形，看起来凹入于页面表面, “U” (下划线) = 注释矩形底部的一条单线.
云层 – 一个整数，表示“多云”的边界，其中
n是一个整数-1 <= n <= 2。值n = 0表示直线（没有云），1 表示小的，2 表示大的半圆，模仿多云的外观。如果是 -1，则没有规格。
- Return type:
字典
MuPDF中的注释图标#
这是可通过名称引用的图标列表，用于注释类型“文本”和“文件附件”。您可以在添加注释时通过 icon 参数使用它们，或者在 Annot.set_name() 中作为参数使用。选择何时使用哪个项目由您自行决定，系统不会阻止您例如将“扬声器”图标用于‘文件附件’。
示例#
更改注释的图形图像。还要更新“作者”和将在弹出窗口中显示的文本：
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查看器显示的弹出窗口）：
脚注