返回顶部

在 Discord 上找到 #pymupdf

Page#

表示文档页面的类。Document.load_page() 或等效地通过索引文档（例如 doc[n]）创建页面对象 - 它没有独立的构造函数。

文档及其页面之间存在父子关系。如果文档被关闭或删除，所有现有页面对象（及其各自的子对象）将变为不可用（“孤立”）：如果使用了页面属性或方法，将引发异常。

为了方便，一些页面方法有对应的 Document 方法。本章末尾有概要。

注意

本章多次使用术语坐标。至少对它有基本了解并熟悉 Coordinates 章节非常重要。

修改页面#

修改页面属性和添加或更改页面内容仅适用于 PDF 文档。

简而言之，以下是您可以使用 PyMuPDF 进行的操作：

修改页面旋转和页面的可见部分（“cropbox”）。
插入图像、其他 PDF 页面、文本和简单的几何对象。
添加注解和表单域。

注意

方法需要坐标（点、矩形）来将内容放置到所需位置。请注意，这些坐标 必须始终 相对于 未旋转 的页面提供（从 v1.17.0 开始）。反之亦然：除了 Page.rect 和 Page.bound()（两者在页面旋转时会反映旋转），所有由方法和属性返回的坐标都与未旋转的页面有关。

因此，例如 Page.get_image_bbox() 的返回值不会因执行 Page.set_rotation() 而改变。这同样适用于 Page.get_text() 返回的坐标、注解矩形等。如果您想找出对象在 旋转后坐标 中的位置，请将坐标与 Page.rotation_matrix 相乘。还有一个其逆矩阵 Page.derotation_matrix，在与其他可能在此方面表现不同的阅读器交互时可以使用。

注意

如果您在页面上添加或更新注解、链接或表单域，并紧接着需要使用它们（即 不离开该页面），您应该在使用这些新或更新的项之前，使用 Document.reload_page() 重新加载页面。

通常建议重新加载页面 - 尽管并非所有情况下都严格要求。然而，与 MuPDF 相比，某些注解和控件类型在 PyMuPDF 中具有扩展功能。未来还可能添加更多此类扩展功能。

重新加载页面可确保您的所有更改都已完全应用于 PDF 结构，这样您就可以安全地创建 Pixmaps 或成功迭代注解、链接和表单域。

方法 / 属性	简要描述
`Page.add_caret_annot()`	仅限 PDF：添加插入符注解
`Page.add_circle_annot()`	仅限 PDF：添加圆形注解
`Page.add_file_annot()`	仅限 PDF：添加文件附件注解
`Page.add_freetext_annot()`	仅限 PDF：添加文本注解
`Page.add_highlight_annot()`	仅限 PDF：添加“高亮”注解
`Page.add_ink_annot()`	仅限 PDF：添加墨迹注解
`Page.add_line_annot()`	仅限 PDF：添加直线注解
`Page.add_polygon_annot()`	仅限 PDF：添加多边形注解
`Page.add_polyline_annot()`	仅限 PDF：添加多线注解
`Page.add_rect_annot()`	仅限 PDF：添加矩形注解
`Page.add_redact_annot()`	仅限 PDF：添加涂黑/删除注解
`Page.add_squiggly_annot()`	仅限 PDF：添加“波浪线”注解
`Page.add_stamp_annot()`	仅限 PDF：添加“图章”注解
`Page.add_strikeout_annot()`	仅限 PDF：添加“删除线”注解
`Page.add_text_annot()`	仅限 PDF：添加注释
`Page.add_underline_annot()`	仅限 PDF：添加“下划线”注解
`Page.add_widget()`	仅限 PDF：添加 PDF 表单域
`Page.annot_names()`	仅限 PDF：注解（和控件）名称列表
`Page.annot_xrefs()`	仅限 PDF：注解（和控件）xrefs 列表
`Page.annots()`	返回页面注解的生成器
`Page.apply_redactions()`	仅限 PDF：处理页面的涂黑/删除操作
`Page.bound()`	页面矩形
`Page.cluster_drawings()`	仅限 PDF：矢量图形的边界框
`Page.delete_annot()`	仅限 PDF：删除注解
`Page.delete_image()`	仅限 PDF：删除图像
`Page.delete_link()`	仅限 PDF：删除链接
`Page.delete_widget()`	仅限 PDF：删除控件/域
`Page.draw_bezier()`	仅限 PDF：绘制三次贝塞尔曲线
`Page.draw_circle()`	仅限 PDF：绘制圆形
`Page.draw_curve()`	仅限 PDF：绘制特殊贝塞尔曲线
`Page.draw_line()`	仅限 PDF：绘制直线
`Page.draw_oval()`	仅限 PDF：绘制椭圆形
`Page.draw_polyline()`	仅限 PDF：连接点序列
`Page.draw_quad()`	仅限 PDF：绘制四边形
`Page.draw_rect()`	仅限 PDF：绘制矩形
`Page.draw_sector()`	仅限 PDF：绘制扇形
`Page.draw_squiggle()`	仅限 PDF：绘制波浪线
`Page.draw_zigzag()`	仅限 PDF：绘制锯齿线
`Page.find_tables()`	在页面上查找表格
`Page.get_drawings()`	获取页面上的矢量图形
`Page.get_fonts()`	仅限 PDF：获取引用的字体列表
`Page.get_image_bbox()`	仅限 PDF：获取嵌入图像的 bbox 和矩阵
`Page.get_image_info()`	获取所有使用图像的元信息列表
`Page.get_image_rects()`	仅限 PDF：`Page.get_image_bbox()` 的改进版本
`Page.get_images()`	仅限 PDF：获取引用的图像列表
`Page.get_label()`	仅限 PDF：返回页面的标签
`Page.get_links()`	获取所有链接
`Page.get_pixmap()`	创建栅格格式的页面图像
`Page.get_svg_image()`	创建 SVG 格式的页面图像
`Page.get_text()`	提取页面文本
`Page.get_textbox()`	提取包含在矩形中的文本
`Page.get_textpage_ocr()`	为页面创建带有 OCR 的 TextPage
`Page.get_textpage()`	为页面创建 TextPage
`Page.get_xobjects()`	仅限 PDF：获取引用的 xobjects 列表
`Page.insert_font()`	仅限 PDF：插入字体供页面使用
`Page.insert_image()`	仅限 PDF：插入图像
`Page.insert_link()`	仅限 PDF：插入链接
`Page.insert_text()`	仅限 PDF：插入文本
`Page.insert_htmlbox()`	仅限 PDF：在矩形中插入 HTML 文本
`Page.insert_textbox()`	仅限 PDF：插入文本框
`Page.links()`	返回页面链接的生成器
`Page.load_annot()`	仅限 PDF：加载特定注解
`Page.load_widget()`	仅限 PDF：加载特定域
`Page.load_links()`	返回页面上的第一个链接
`Page.new_shape()`	仅限 PDF：创建一个新的 Shape
`Page.recolor()`	仅限 PDF：更改对象的颜色空间
`Page.remove_rotation()`	仅限 PDF：将页面旋转设置为 0
`Page.replace_image()`	仅限 PDF：替换图像
`Page.search_for()`	搜索字符串
`Page.set_artbox()`	仅限 PDF：修改 `/ArtBox`
`Page.set_bleedbox()`	仅限 PDF：修改 `/BleedBox`
`Page.set_cropbox()`	仅限 PDF：修改 `cropbox`（可见页面）
`Page.set_mediabox()`	仅限 PDF：修改 `/MediaBox`
`Page.set_rotation()`	仅限 PDF：设置页面旋转
`Page.set_trimbox()`	仅限 PDF：修改 `/TrimBox`
`Page.show_pdf_page()`	仅限 PDF：显示 PDF 页面图像
`Page.update_link()`	仅限 PDF：修改链接
`Page.widgets()`	返回页面域的生成器
`Page.write_text()`	写入一个或多个 TextWriter 对象
`Page.cropbox_position`	`cropbox` 的位移
`Page.cropbox`	页面的 `cropbox`
`Page.artbox`	页面的 `/ArtBox`
`Page.bleedbox`	页面的 `/BleedBox`
`Page.trimbox`	页面的 `/TrimBox`
`Page.derotation_matrix`	仅限 PDF：获取未旋转页面空间中的坐标
`Page.first_annot`	页面上的第一个 Annot
`Page.first_link`	页面上的第一个 Link
`Page.first_widget`	页面上的第一个控件（表单域）
`Page.mediabox_size`	`mediabox` 的右下角点
`Page.mediabox`	页面的 `mediabox`
`Page.number`	页码
`Page.parent`	所属文档对象
`Page.rect`	页面矩形
`Page.rotation_matrix`	仅限 PDF：获取旋转后页面空间中的坐标
`Page.rotation`	仅限 PDF：页面旋转
`Page.transformation_matrix`	仅限 PDF：在 PDF 和 MuPDF 空间之间转换
`Page.xref`	仅限 PDF：页面 `xref`

类 API

class Page#

bound()#

确定页面的矩形。与属性 Page.rect 相同。对于 PDF 文档，这通常也与 mediabox 和 cropbox 重合，但并非总是如此。例如，如果页面旋转了，此方法会反映旋转结果 - 但 Page.cropbox 不会改变。

返回类型:: Rect

add_caret_annot(point)#

仅限 PDF：添加插入符图标。插入符注解是一个视觉符号，通常用于指示页面上存在文本编辑。

参数:: point (point_like) – 包含 MuPDF 提供的图标的 20 x 20 矩形的左上角点。
返回类型:: Annot
返回:: 创建的注解。描边颜色蓝色 = (0, 0, 1)，不支持填充颜色。

显示/隐藏历史

v1.16.0 新增

add_text_annot(point, text, icon='Note')#

仅限 PDF：添加一个带有附带文本的注释图标（“便利贴”）。只有图标可见，附带文本是隐藏的，许多 PDF 阅读器可以通过将鼠标悬停在符号上来查看。

参数:

point (point_like) – 包含 MuPDF 提供的“note”图标的 20 x 20 矩形的左上角点。
text (str) – 注释文本。双击或将鼠标悬停在图标上时会显示此文本。可以包含任何拉丁字符。
icon (str) – 选择“Note”（默认）、“Comment”、“Help”、“Insert”、“Key”、“NewParagraph”、“Paragraph”中的一个作为包含文本的视觉符号[4]。（v1.16.0 新增）

返回类型:

Annot

返回:

创建的注解。描边颜色黄色 = (1, 1, 0)，不支持填充颜色。

add_freetext_annot(rect, text, *, fontsize=11, fontname='helv', text_color=0, fill_color=None, border_width=0, dashes=None, callout=None, line_end=PDF_ANNOT_LE_OPEN_ARROW, opacity=1, align=TEXT_ALIGN_LEFT, rotate=0, richtext=False, style=None)#

仅限 PDF：在给定矩形中添加文本。可以选择通过指定两个或三个 point-like 对象来请求“标注”形状的外观——见下文。

参数:

rect (rect_like) – 应插入文本的矩形。文本会在框宽度处自动换行。不适合矩形的文本部分将不可见，且不会有警告。
text (str) – 文本。可以包含拉丁语、希腊语、西里尔语、中文、日语和韩语字符的任意组合。如果 richtext=True（见下文），字符串将被解释为 HTML 语法。这为实现吸引人的效果提供了多种方式。
fontsize (float) – fontsize。默认值为 11。如果 richtext=True 则忽略。
fontname (str) –
字体名称。默认值为“Helv”。如果 richtext=True 则忽略，否则适用以下 限制：
- 接受的替代方案有“Helv”（Helvetica）、“Cour”（Courier）、“TiRo”（Timnes-Roman）、“ZaDb”（ZapfDingBats）和“Symb”（Symbol）。名称可以缩写为前两个字符，例如“Cour”的“Co”，接受小写。
- 不支持 字体的粗体或斜体变体。
text_color (list,tuple,float) – 文本颜色。默认为黑色。如果 richtext=True 则忽略。
fill_color (list,tuple,float) – 填充颜色。在适用时，此颜色用于 rect 和标注线的终点。默认为 None。
border_color (list,tuple,float) – 仅当 richtext=True 时，此参数 才生效。否则，使用 text_color。
border_width (float) – 边框和 callout 线的宽度。默认值为 0（无边框），在这种情况下，标注线可能仍以极细的线宽出现，具体取决于所使用的 PDF 阅读器。无论如何，此值必须为正才能看到边框线。
dashes (list,tuple) – 浮点数列表，指定边框和标注线应如何绘制虚线。默认为 None。
callout (list,tuple) – 包含两个或三个 point_like 对象的列表/元组，这些对象将被解释为多达两个线段的终点 [、弯折点] 和起点（按此顺序），将此注解转换为标注形状。
line_end (int) – 标注线的线段末端符号。它绘制在 callout 列表中指定的第一个点处。默认是一个开放箭头。有关可能的值，请参阅 Annotation Line Ending Styles。
opacity (float) – 一个浮点数 0 <= opacity < 1，使注解透明。默认不透明。
align (int) – 文本对齐方式，可以是 TEXT_ALIGN_LEFT、TEXT_ALIGN_CENTER、TEXT_ALIGN_RIGHT 中的一个 - 不支持 对齐。如果 richtext=True 则忽略。
rotate (int) – 文本方向。接受的值是 90° 的整数倍。无效条目将获得旋转 0。
richtext (bool) – 将 text 视为 HTML 语法。这允许实现粗体、斜体、任意文本颜色、字体大小、包括两端对齐在内的文本对齐方式等——只要 PDF 对 HTML 和样式指令的子集支持即可。这类似于 Page.insert_htmlbox() 中发生的情况。例如，如果遇到标准字体中不包含的字符，基础库将引入所需的字体。如果设置了此选项，某些参数将被忽略，如上所述。默认值为 False。
style (str) – 提供可选的 CSS 语法 HTML 样式信息。如果 richtext=False 则忽略。

返回类型:

Annot

返回:

创建的注解。

显示/隐藏历史

v1.19.6 更改：添加边框颜色参数

add_file_annot(pos, buffer, filename, ufilename=None, desc=None, icon='PushPin')#

仅限 PDF：在指定位置添加带有“图钉”图标的文件附件注解。

参数:

pos (point_like) – 包含 MuPDF 提供的“图钉”图标的 18x18 矩形的左上角点。
buffer (bytes,bytearray,BytesIO) –
要存储的数据（实际文件内容、任何数据等）。

v1.14.13 更改：现在也支持 io.BytesIO。
filename (str) – 与数据关联的文件名。
ufilename (str) – 可选的 PDF unicode 版本文件名。默认为 filename。
desc (str) – 文件的可选描述。默认为 filename。
icon (str) – 选择“PushPin”（默认）、“Graph”、“Paperclip”、“Tag”中的一个作为附加数据的视觉符号[4]。（v1.16.0 新增）

返回类型:

Annot

返回:

创建的注解。描边颜色黄色 = (1, 1, 0)，不支持填充颜色。

add_ink_annot(list)#

仅限 PDF：添加“手绘”涂鸦注解。

参数:: list (sequence) – 包含一个或多个列表的列表，每个列表包含 point_like 项。这些子列表中的每个项都被解释为一个 Point，并绘制连接线穿过它。因此，单独的子列表表示单独的绘图线。
返回类型:: Annot
返回:: 创建的注解，默认外观为黑色 =(0, 0, 0)，线宽 1。不支持填充颜色。

add_line_annot(p1, p2)#

仅限 PDF：添加直线注解。

参数:

p1 (point_like) – 直线的起点。
p2 (point_like) – 直线的终点。

返回类型:

Annot

返回:

创建的注解。它以红色 =(1, 0, 0) 线（描边）颜色和线宽 1 绘制。不支持填充颜色。注解矩形 会自动创建，以包含两个点，每个点周围环绕着半径为 3 * 线宽的圆，以便为任何线段末端符号留出空间。

add_rect_annot(rect)#

add_circle_annot(rect)#

仅限 PDF：添加矩形或圆形注解。

参数:: rect (rect_like) – 在其中绘制圆形或矩形的矩形，必须是有限且非空的。如果矩形不是等边的，则绘制一个椭圆。
返回类型:: Annot
返回:: 创建的注解。它以红色 =(1, 0, 0) 线（描边）颜色、线宽 1 绘制，支持填充颜色。

涂黑/删除#

add_redact_annot(quad, text=None, fontname=None, fontsize=11, align=TEXT_ALIGN_LEFT, fill=(1, 1, 1), text_color=(0, 0, 0), cross_out=True)#

仅限 PDF：添加涂黑/删除注解。涂黑/删除注解标识应从文档中删除内容的区域。添加此类注解是两步过程的第一步。它使后续步骤中要删除的内容可见，该后续步骤是 Page.apply_redactions()。

参数:

quad (quad_like,rect_like) – 指定要删除的（矩形）区域，此区域始终等于注解矩形。它可以是一个 rect_like 或 quad_like 对象。如果指定了四边形，则取其外包矩形。
text (str) – 应用涂黑/删除（并因此删除旧内容）后放置在矩形中的文本。（v1.16.12 新增）
fontname (str) – 当给定 text 时使用的字体，否则忽略。仅支持 CJK 和 PDF Base 14 Fonts。除此之外，与 Page.insert_textbox() 适用相同的规则 – 这是 Page.apply_redactions() 方法内部调用的。
fontsize (float) – 用于替换文本的 fontsize。如果文本太大无法适应，将尝试多次插入，逐渐减小 fontsize 至不小于 4。如果届时文本仍然无法适应，则完全不进行文本插入。（v1.16.12 新增）
align (int) – 替换文本的水平对齐方式。可用值请参阅 insert_textbox()。垂直对齐方式为（大约）居中。
fill (sequence) – 应用密文后矩形的填充颜色。默认值为白色 = (1, 1, 1)，如果指定为 None 也会采用此值。要完全取消填充颜色，请指定 False。在这种情况下，矩形保持透明。（v1.16.12 新增）
text_color (sequence) – 替换文本的颜色。默认值为黑色 = (0, 0, 0)。（v1.16.12 新增）
cross_out (bool) – 为标注矩形添加两条对角线。（v1.17.2 新增）

返回类型:

Annot

返回:

创建的标注。其标准外观为一个红色矩形（无填充颜色），可选地显示两条对角线。颜色、线宽、虚线、不透明度和混合模式现在可以通过 Annot.update() 设置和应用，与其他标注一样。（v1.17.2 修改）

显示/隐藏历史

v1.16.11 新增

apply_redactions(images=PDF_REDACT_IMAGE_PIXELS | 2, graphics=PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED | 2, text=PDF_REDACT_TEXT_REMOVE | 0)#

仅限 PDF：删除页面上任意密文矩形中包含的所有内容。

此方法应用密文，然后删除页面上的所有密文标注。

参数:

images (int) – 如何处理重叠的图像。默认值 (2) 会涂黑重叠的像素。PDF_REDACT_IMAGE_NONE | 0 表示忽略，PDF_REDACT_IMAGE_REMOVE | 1 表示完全移除与任何密文标注重叠的图像。选项 PDF_REDACT_IMAGE_REMOVE_UNLESS_INVISIBLE | 3 仅移除实际可见的图像。
graphics (int) – 如何处理重叠的矢量图形（也称为“线稿”或“绘图”）。默认值 (2) 会移除任何重叠的矢量图形。PDF_REDACT_LINE_ART_NONE | 0 表示忽略，PDF_REDACT_LINE_ART_REMOVE_IF_COVERED | 1 会移除完全包含在密文标注中的图形。移除线稿时，请注意描边矢量图形（即类型“s”或“sf”）具有比预期更大范围的边界矩形：首先，至少需要向每个方向添加路径线宽的 50% 才能真正包含所有图形。如果提供了所谓的“斜接极限”（参见 PDF 规范第 121 页），则放大值为 miter * width / 2。因此，在使用所有默认值（width = 1，miter = 10）时，密文矩形应在每个方向上至少大 5 个点。
text (int) – 是否处理重叠的文本。默认值 PDF_REDACT_TEXT_REMOVE | 0 会移除边界框与任何密文矩形有非空重叠的所有字符。这符合密文标注最初的法律/数据保护意图。然而，其他用例可能需要在处理矢量图形或图像的同时保留文本。这可以通过设置 text=True|PDF_REDACT_TEXT_NONE | 1 来实现。这不符合密文标注的数据保护意图。请自行承担风险。

返回:

如果至少处理了一个密文标注，则返回 True，否则返回 False。

注意

包含在密文矩形中的文本将从页面中物理上移除（假设使用合适的垃圾收集选项调用 Document.save()），并且不再出现在文本提取或其他任何地方。所有密文标注也将被移除。其他标注不受影响。
所有重叠的链接将被移除。如果链接的矩形覆盖了文本，则只移除文本的重叠部分。类似地，适用于被链接矩形覆盖的图像。
对于默认选项 PDF_REDACT_IMAGE_PIXELS，图像的重叠部分将被涂黑（v1.18.0 修改）。选项 0 不触及任何图像，选项 1 将移除任何有重叠的图像。
对于选项 images=PDF_REDACT_IMAGE_REMOVE，仅移除此页面中对图像的引用 - 不一定移除图像本身。图像仅在文件不再引用时才完全从文件中移除（假设有合适的垃圾收集选项）。
对于选项 images=PDF_REDACT_IMAGE_PIXELS，会创建一个新的 PNG 格式图像，页面将使用此新图像替换原始图像。原始图像在此过程中不会被删除或替换，因此其他页面可能仍显示原始图像。此外，当前新的、修改后的 PNG 图像是未压缩存储的。在保存时选择合适的垃圾收集方法和压缩选项时，请记住这些方面。
文本移除是按字符进行的：如果字符的边界框与密文矩形有非空重叠，则移除该字符（MuPDF v1.17 修改）。根据字体属性和/或所选的行高，可能会删除不期望的文本部分。在文本搜索之前，使用参数 True 调用 Tools.set_small_glyph_heights() 可能有助于防止此问题。
密文是一种简单的方法，可以在 PDF 中替换单个单词，或者只是物理地移除它们。使用某种文本提取或搜索方法找到单词“secret”，并为每个出现的位置插入密文，将替换文本设置为“xxxxxx”。
- 如果替换文本比原始文本长，请谨慎使用——这可能导致外观尴尬、换行或根本没有新文本出现。
- 出于多种原因，新文本的位置可能与旧文本不在同一行上——特别是如果替换字体不是 CJK 或 PDF Base 14 字体之一。

显示/隐藏历史

v1.16.11 新增
v1.16.12 修改：之前的 mark 参数已删除。取而代之的是，相应的矩形填充了每个密文标注的单独 fill 颜色。如果标注中给定了 text，则会调用 insert_textbox()，使用密文提供的参数插入文本。
v1.18.0 修改：添加了处理重叠密文区域图像的选项。
v1.23.27 修改：添加了移除图形的选项。
v1.24.2 修改：添加了选项 keep_text 以保持文本不受影响。

add_polyline_annot(points)#

add_polygon_annot(points)#

仅限 PDF：添加一个由连接给定点的线组成的标注。Polygon 的第一个和最后一个点会自动连接，而 PolyLine 不会。矩形会自动创建为包含这些点的最小矩形，每个点周围有一个半径为 3（= 3 * 线宽）的圆。下图显示了一个经过颜色和线端修改的“PolyLine”。

参数:: points (list) – point_like 对象的列表。
返回类型:: Annot
返回:: 创建的标注。它使用黑色线条、线宽 1 绘制，无填充颜色但支持填充颜色。使用 Annot 的方法进行任何更改，以实现类似效果。

add_underline_annot(quads=None, start=None, stop=None, clip=None)#

add_strikeout_annot(quads=None, start=None, stop=None, clip=None)#

add_squiggly_annot(quads=None, start=None, stop=None, clip=None)#

add_highlight_annot(quads=None, start=None, stop=None, clip=None)#

仅限 PDF：这些标注通常用于标记文本，这些文本之前已经以某种方式定位（例如通过 Page.search_for()）。但这并非必须：您可以自由地“标记”任何内容。

每种标注类型选择标准（仅描边 - 不支持填充颜色）颜色：高亮是黄色，删除线是红色，下划线是绿色，波浪线是洋红色。

这四个方法都将参数转换为 Quad 对象列表。然后计算标注矩形以包含所有这些四边形。

注意

search_for() 返回 Rect 或 Quad 对象列表。这样的列表可以直接用作这些标注类型的参数，并将为搜索字符串的所有出现位置提供一个共同的标注。

>>> # prefer quads=True in text searching for annotations!
>>> quads = page.search_for("pymupdf", quads=True)
>>> page.add_highlight_annot(quads)

注意

显然，文本标记标注需要知道要标记区域的顶部、底部、左侧和右侧。如果参数是四边形，这些信息由四边形点的顺序给出。相反，矩形提供的信息要少得多——这可以通过一个事实来说明：可以使用矩形的四个角构造 4！= 24 个不同的四边形。

因此，我们强烈建议对文本搜索使用 quads 选项，以确保标注正确。类似地，对使用 Page.get_text() 的“dict”/“rawdict”选项提取的文本跨度进行标记时也应考虑这一点。有关在这种情况下如何计算四边形的更多详细信息，请参阅 FAQ 中“如何标记非水平文本”部分。

参数:

quads (rect_like,quad_like,list,tuple) – 要标记的位置 – 矩形或四边形。（v1.14.20 修改）列表或元组必须包含 rect_like 或 quad_like 项目（甚至可以混合使用）。每个项目都必须是有限的、凸的且非空的（适用时）。如果要使用以下参数，请将此参数设置为 None（v1.16.14 修改）。反之亦然：如果不是 None，则剩余参数必须是 None。
start (point_like) – 在此点开始标记文本。默认为 clip 的左上角点。如果 quads 为 None，则必须提供此参数。（v1.16.14 新增）
stop (point_like) – 在此点停止标记文本。默认为 clip 的右下角点。如果 quads 为 None，则必须使用此参数。（v1.16.14 新增）
clip (rect_like) – 仅考虑与此区域相交的文本行。默认为页面矩形。仅在提供 start 和 stop 时使用。（v1.16.14 新增）

返回类型:

Annot 或 None（v1.16.14 修改）。

返回:

创建的标注。如果 quads 是一个空列表，则不创建标注（v1.16.14 修改）。

注意

您可以使用参数 start、stop 和 clip 来高亮介于 start 和 stop 两点之间的连续行（从 v1.16.14 开始）。利用 clip 可以进一步缩小选定行的边界框，从而处理例如多列页面。以下在三列页面上的多行高亮是通过指定两个红点并相应设置 clip 创建的。

cluster_drawings(clip=None, drawings=None, x_tolerance=3, y_tolerance=3, final_filter=True)#

根据几何接近度对矢量图形（同义词：线稿或绘图）进行聚类。该方法遍历 Page.get_drawings() 的输出，并将 path["rect"] 彼此距离小于容差值（在参数中给出）的路径连接起来。结果是矩形列表，每个矩形包含表格（带网格线）、饼图、柱状图等。

参数:

clip (rect_like) – 仅考虑此区域内的路径。默认值为整个页面。
drawings (list) – （可选）提供之前生成的 Page.get_drawings() 输出。如果为 None，则方法将执行该方法。
y_tolerance (float x_tolerance /) – 假定矢量图形彼此足够接近，属于同一矩形。默认值为 3 点。
final_filter (bool) – 如果为 True（默认），方法将尝试删除宽度或高度小于相应容差值的矩形。如果为 False，则不执行此类过滤。

find_tables(clip=None, strategy=None, vertical_strategy=None, horizontal_strategy=None, vertical_lines=None, horizontal_lines=None, snap_tolerance=None, snap_x_tolerance=None, snap_y_tolerance=None, join_tolerance=None, join_x_tolerance=None, join_y_tolerance=None, edge_min_length=3, min_words_vertical=3, min_words_horizontal=1, intersection_tolerance=None, intersection_x_tolerance=None, intersection_y_tolerance=None, text_tolerance=None, text_x_tolerance=None, text_y_tolerance=None, add_lines=None, add_boxes=None, paths=None)#

在页面上查找表格并返回一个包含相关信息的对象。通常，大多数参数使用默认值即可。仅在特殊情况下才需要调整。

参数:

clip (rect_like) – 指定要在页面矩形内考虑的区域并忽略其余部分。默认为整个页面。
strategy (str) –
请求表格检测策略。有效值为 "lines"、"lines_strict" 和 "text"。

默认值为 "lines"，它使用页面上的所有矢量图形来检测网格线。

策略 "lines_strict" 忽略无边框的矩形矢量图形。有时单个文本块有背景颜色，可能导致错误的列或线。此策略会忽略它们，从而可以提高检测精度。

如果指定为 "text"，则使用文本位置生成“虚拟”列和/或行边界。使用 min_words_* 指定考虑其坐标所需的单词数量。

请改用参数 vertical_strategy 和 horizontal_strategy 进行更细致的维度处理。
horizontal_lines (sequence[floats]) – 行的 y 坐标。如果提供，将不再尝试识别额外的表格行。这会影响表格检测。
vertical_lines (sequence[floats]) – 列的 x 坐标。如果提供，将不再尝试识别额外的表格列。这会影响表格检测。
min_words_vertical (int) – 与垂直策略选项 "text" 相关：至少需要这么多单词才能建立虚拟列边界。
min_words_horizontal (int) – 与水平策略选项 "text" 相关：至少需要这么多单词才能建立虚拟行边界。
snap_tolerance (float) – y 值差异不超过此值的任意两条水平线将被吸附为一条。垂直线同理。默认值为 3。可以使用 snap_x_tolerance 和 snap_y_tolerance 分别指定不同维度（x 和 y）的值。
join_tolerance (float) – 如果两条线的端点和起点差异不超过此值（点为单位），则它们将被连接为一条线。默认值为 3。可以使用 join_x_tolerance 和 join_y_tolerance 分别指定不同维度（x 和 y）的值。
edge_min_length (float) – 如果线的长度不超过此值（点为单位），则忽略该线。默认值为 3。
intersection_tolerance (float) – 将线组合成单元格边框时，正交线必须在此值（点为单位）范围内才被视为相交。默认值为 3。可以使用 intersection_x_tolerance 和 intersection_y_tolerance 分别指定不同维度（x 和 y）的值。
text_tolerance (float) – 字符之间的距离不超过此值（点为单位）时才会被组合成单词。默认值为 3。可以使用 text_x_tolerance 和 text_y_tolerance 分别指定不同维度（x 和 y）的值。
add_lines (tuple,list) – 指定一个“线”列表（即 point_like 对象对）作为额外的“虚拟”矢量图形。这些线可能有助于表格和/或单元格检测，但不会以其他方式影响检测策略。特别是，与参数 horizontal_lines 和 vertical_lines 不同，它们不会阻止以其他方式检测行或列。这些线将根据连接、吸附、相交、最小长度和包含在 clip 矩形中的规则，与“真实”矢量图形完全相同处理。类似地，不平行于任何坐标轴的线将被忽略。
add_boxes (tuple,list) – 指定一个矩形列表（rect_like 对象）作为额外的“虚拟”矢量图形。这些矩形可能有助于表格和/或单元格检测，但不会以其他方式影响检测策略。特别是，与参数 horizontal_lines 和 vertical_lines 不同，它们不会阻止以其他方式检测行或列。这些矩形将根据连接、吸附、相交、最小长度和包含在 clip 矩形中的规则，与“真实”矢量图形完全相同处理。
paths (list) – 矢量图形列表，格式与 Page.get_drawings() 返回的格式相同。使用此参数将阻止方法自行提取矢量图形。如果矢量图形已可用，这非常有用。可以显著节省执行时间。

返回:

一个 TableFinder 对象，具有以下重要属性：

cells：页面上所有被识别为表格单元格（跨所有表格）的 bbox 列表。每个单元格是一个 rect_like 坐标元组 (x0, y0, x1, y1) 或 None。
tables：Table 对象列表。如果页面没有表格，则此项为 []。单个表格可以作为此列表中的项目找到。但是 TableFinder 对象本身也是其表格的序列。这意味着如果 tabs 是一个 TableFinder 对象，则表格“n”可以通过 tabs.tables[n] 以及更简洁的 tabs[n] 来获取。
Table 对象具有以下属性：
- bbox：表格的边界框，为元组 (x0, y0, x1, y1)。
- cells：表格单元格的边界框（元组列表）。单元格也可能是 None。
- extract()：此方法将返回每个表格单元格的文本内容，格式为字符串列表的列表。
- to_markdown()：此方法将表格返回为markdown 格式的字符串（兼容 Github）。Markdown 查看器可以将字符串渲染为表格。此输出针对小标记大小进行了优化，这对 LLM/RAG 输入尤其有利。Pandas DataFrames（请参见下面的 to_pandas() 方法）提供了等效的 markdown 表格输出，但对人眼而言可读性更好。单元格中的任何换行符（n）都替换为 HTML 换行标签 <br>。
- to_pandas()：此方法将表格返回为 pandas DataFrame。DataFrame 是非常通用的对象，允许进行大量的表格操作方法并将输出转换为近 20 种著名格式，其中包括 Excel 文件、CSV、JSON、markdown 格式表格等等。DataFrame.to_markdown() 生成与 Github 兼容的 markdown 格式，并为人类可读性进行了优化。然而，此方法除了 pandas 本身之外，还需要安装 tabulate 包。
- header：一个 TableHeader 对象，包含表格的标题信息。
- col_count：一个整数，包含表格的列数。
- row_count：一个整数，包含表格的行数。
- rows：TableRow 对象列表，包含两个属性，bbox 是行的边界框，cells 是包含在该行中的表格单元格列表。
TableHeader 对象具有以下属性：
- bbox：标题的边界框。
- cells：包含相应列名称的边界框列表。
- names：字符串列表，包含每个单元格边界框的文本。它们代表列名——在将表格导出到 pandas DataFrames、markdown 等时使用。
- external：一个布尔值，指示标题边界框是否在表体之外（True）或不在。表格标题绝不会被 TableFinder 逻辑识别。因此，如果 external 为 True，则标题单元格不属于 TableFinder 识别的任何单元格。如果 external == False，则第一个表格行是标题。

请查看这些 Jupyter notebooks，它们涵盖了标准情况，如同一页面上的多个表格或跨页连接表格片段。

注意

TableFinder 对象以及其所有表格的生命周期等于页面的生命周期。如果页面对象被删除或重新分配，则所有表格将不再有效。

在页面可用性之外保留表格内容的唯一方法是通过方法 Table.to_markdown()、Table.to_pandas() 或 Table.extract() 的副本（例如 Table.extract()[:]）来提取它。

注意

一旦通过 to_pandas() 将表格提取到 Pandas DataFrame 中，就可以使用 Pandas API 轻松转换为其他文件类型。

表格转换为 Markdown，使用 to_markdown
表格转换为 JSON，使用：to_json
表格转换为 Excel，使用：to_excel
表格转换为 CSV，使用：to_csv
表格转换为 HTML，使用：to_html
表格转换为 SQL，使用：to_sql

显示/隐藏历史

版本 1.23.0 新增
版本 1.23.19 修改：新增参数 add_lines。

重要

如果您更喜欢使用 pdf2docx extract tables method，它也能够提取表格。

add_stamp_annot(rect, stamp=0)#

仅限 PDF：添加“橡皮图章”标注，例如指示文档的预期用途（“草稿”、“机密”等）。参数可以是整数，用于从预定义标准文本数组中选择文本，也可以是图像。

参数:

rect (rect_like) – 放置标注的矩形。
stamp (multiple) –
可用选项如下：
- 图章文本的 ID 号（整数）。可用图章请参见图章标注图标。
- 指定图像文件路径的字符串。
- bytes、bytearray 或 io.BytesIO 对象，表示内存中的图像。
- 一个 Pixmap 对象。

基于文本的图章
- Annot.rect 会自动计算为宽高比为 width:height = 3.8 且能适应提供的 rect 的最大矩形。其位置垂直和水平居中。
- 选择的字体是“Times Bold”，文本将为大写。
- 外观可以通过 Annot.set_opacity() 和设置“描边”颜色来修改。根据 PDF 规范，图章标注没有“填充”颜色。
基于图像的图章
- 图像缩放到适应 Rect 矩形，使得图像中心与 Rect 中心重合。图像的宽高比得以保留，因此图像可能无法填满整个矩形。但是，给定的矩形宽度或高度至少有一个会被完全覆盖。
- 标注可以通过 Annot.set_opacity() 进行修改。因此，此方法是一种即使不存在 alpha 通道也能透明显示图像的方式。
- 设置颜色对图像图章无效。
- 不支持旋转基于图像的图章。设置旋转可能导致意想不到的结果。

add_widget(widget)#

仅限 PDF：将 PDF 表单字段（“widget”）添加到页面。这也会将 PDF 转换为表单 PDF。由于 widget 有大量不同的可用选项，我们开发了一个新类 Widget，其中包含可能的 PDF 字段属性。创建和更新表单字段都必须使用它。

参数:: widget (Widget) – 必须预先创建的 Widget 对象。
返回:: 一个 widget 标注。

delete_annot(annot)#

移除现在将包含任何绑定的“Popup”或响应标注及相关对象（v1.16.6 修改）。

仅限 PDF：从页面中删除标注并返回下一个标注。

参数:: annot (Annot) – 要删除的标注。
返回类型:: Annot
返回:: 删除标注后的下一个标注。请记住，物理删除需要使用垃圾收集选项大于 0 将文档保存到新文件。

delete_widget(widget)#

仅限 PDF：从页面中删除字段并返回下一个字段。

参数:: widget (Widget) – 要删除的 widget。
返回类型:: Widget
返回:: 删除 widget 后的下一个 widget。请记住，物理删除需要使用垃圾收集选项大于 0 将文档保存到新文件。

显示/隐藏历史

（v1.18.4 新增）

delete_link(linkdict)#

仅限 PDF：从页面中删除指定的链接。参数必须是 get_links() 的原始项之一，详见 get_links() 条目描述。这样做的原因是字典的 “xref” 键，它标识了要删除的 PDF 对象。

参数:: linkdict (dict) – 要删除的链接。

insert_link(linkdict)#

仅限 PDF：在此页面上插入新链接。参数必须是 get_links() 提供的格式字典，详见 get_links() 条目描述。

参数:: linkdict (dict) – 要插入的链接。

update_link(linkdict)#

仅限 PDF：修改指定的链接。参数必须是 get_links() 的（修改后的）原始项之一，详见 get_links() 条目描述。这样做的原因是字典的 “xref” 键，它标识了要更改的 PDF 对象。

参数:: linkdict (dict) – 要修改的链接。

警告

如果更新/插入 URI 链接（"kind": LINK_URI），请确保 "uri" 键的值以明确的字符串开头，例如 "http://"、"https://"、"file://"、"ftp://"、"mailto:" 等。否则——根据您的浏览器或其他“消费者”软件——意外的默认假设可能导致不需要的行为。

get_label()#

仅限 PDF：返回页面的标签。

返回类型:: str
返回:: 标签字符串，例如罗马数字编号的“vii”，或如果未定义则为“”。

显示/隐藏历史

v1.18.6 新增

get_links()#

检索页面的所有链接。

返回类型:: 列表
返回:: 字典列表。有关字典条目的描述，请参阅 get_links() 条目描述。如果您打算更改页面的链接，请务必使用此方法或 Page.links() 方法。

links(kinds=None)#

返回页面链接的生成器。结果与 Page.get_links() 的条目相同。

参数:: kinds (sequence) – 用于向下选择一个或多个链接类型的整数序列。默认为所有链接。示例：kinds=(pymupdf.LINK_GOTO,) 将仅返回内部链接。
返回类型:: 生成器
返回:: 每次迭代中 Page.get_links() 的一个条目。

显示/隐藏历史

v1.16.4 新增

annots(types=None)#

返回页面标注的生成器。

参数:

types (sequence) – 用于向下选择一个或多个标注类型的整数序列。默认为所有标注。示例：types=(pymupdf.PDF_ANNOT_FREETEXT, pymupdf.PDF_ANNOT_TEXT) 将仅返回“FreeText”和“Text”标注。

返回类型:

生成器

返回:

每次迭代中一个 Annot。

注意

您无法在此生成器内部安全地更新标注。这是因为大多数标注更新需要通过 page = doc.reload_page(page) 重新加载页面。要规避此限制，请先创建一个标注 xref 号列表，然后迭代这些号码：

In [4]: xrefs = [annot.xref for annot in page.annots(types=[...])]
In [5]: for xref in xrefs:
   ...:     annot = page.load_annot(xref)
   ...:     annot.update()
   ...:     page = doc.reload_page(page)
In [6]:

显示/隐藏历史

v1.16.4 新增

widgets(types=None)#

返回页面表单字段的生成器。

参数:: types (sequence) – 用于向下选择一个或多个 widget 类型的整数序列。默认为所有表单字段。示例：types=(pymupdf.PDF_WIDGET_TYPE_TEXT,) 将仅返回“Text”字段。
返回类型:: 生成器
返回:: 每次迭代中一个 Widget。

显示/隐藏历史

v1.16.4 新增

write_text(rect=None, writers=None, overlay=True, color=None, opacity=None, keep_proportion=True, rotate=0, oc=0)#

仅限 PDF：将一个或多个 TextWriter 对象的文本写入页面。

参数:

rect (rect_like) – 放置文本的位置。如果省略，则使用文本写入器的矩形并集。
writers (sequence) – 一个非空的 TextWriter 对象元组/列表或单个 TextWriter。
opacity (float) – 设置透明度，覆盖文本写入器中的相应值。
color (sequ) – 设置文本颜色，覆盖文本写入器中的相应值。
overlay (bool) – 将文本放在前景或背景。
keep_proportion (bool) – 保持宽高比。
rotate (float) – 以任意角度旋转文本。
oc (int) – OCG 或 OCMD 的 xref。（v1.18.4 新增）

注意

参数 overlay, keep_proportion, rotate 和 oc 的含义与 Page.show_pdf_page() 中的含义相同。

显示/隐藏历史

v1.16.18 新增

insert_text(point, text, *, fontsize=11, fontname='helv', fontfile=None, idx=0, color=None, fill=None, render_mode=0, miter_limit=1, border_width=0.05, encoding=TEXT_ENCODING_LATIN, rotate=0, morph=None, stroke_opacity=1, fill_opacity=1, overlay=True, oc=0)#

仅限 PDF：在 point_like point 处开始插入文本行。请参阅 Shape.insert_text()。

显示/隐藏历史

v1.18.4 修改

insert_textbox(rect, buffer, *, fontsize=11, fontname='helv', fontfile=None, idx=0, color=None, fill=None, render_mode=0, miter_limit=1, border_width=1, encoding=TEXT_ENCODING_LATIN, expandtabs=8, align=TEXT_ALIGN_LEFT, charwidths=None, rotate=0, morph=None, stroke_opacity=1, fill_opacity=1, oc=0, overlay=True)#

仅限 PDF：在指定的 rect_like rect 中插入文本。参见 Shape.insert_textbox()。

显示/隐藏历史

v1.18.4 修改

insert_htmlbox(rect, text, *, css=None, scale_low=0, archive=None, rotate=0, oc=0, opacity=1, overlay=True)#

仅限 PDF： 在指定的矩形中插入文本。此方法与 Page.insert_textbox() 和 TextWriter.fill_textbox() 方法相似，但功能强大得多。这是通过让 Story 对象执行所有必要的处理来实现的。

参数 text 可以是字符串，如同其他方法一样。但它将被解释为 HTML 源码，因此也可能包含 HTML 语言元素——包括样式。可以使用 css 参数传入额外的样式指令。
自动换行在单词边界处生成。可以使用“软连字符”字符 ""（或 ）来实现连字符断字，从而也可能导致换行。然而，强制换行只能通过 HTML 标签 <br> 实现——\n 会被忽略，并被视为一个空格。
使用此方法可以实现以下功能
- 样式效果，如粗体、斜体、文本颜色、文本对齐、字体大小或字体切换。
- 文本可以包含任意语言——包括从右到左的语言。
- 梵文等亚洲多种文字具有高度复杂的连字系统，其中两个或多个 Unicode 字符共同形成一个字形。Story 使用软件包 HarfBuzz 来处理这些问题并生成正确的输出。
- 还可以通过 HTML 标签 <img> 包含图像——Story 将处理适当的布局。这是插入图像的一种替代选项，相较于 Page.insert_image()。
- 可以在文本中包含 HTML 表格（标签 <table>），并且将得到适当处理。
- 如果存在链接，则会自动生成。
如果内容不适合矩形，开发者有两种选择
- 要么只被告知此情况（并接受无操作，就像其他文本框插入方法一样），
- 要么（scale_low=0 - 默认值）按比例缩小内容直到其适合。

参数:

rect (rect_like) – 页面上接收文本的矩形。
text (str,Story) – 要写入的文本。可以包含纯文本和带有样式指令的 HTML 标签的混合。或者，可以指定一个 Story 对象（在这种情况下将跳过内部 Story 生成步骤）。Story 必须已生成并包含所有必需的样式和 Archive 信息。
css (str) – 可选字符串，包含额外的 CSS 指令。如果 text 是 Story，则忽略此参数。
scale_low (float) – 如有必要，按比例缩小内容直到其适合目标矩形。这设置了缩小的下限。默认值为 0，表示无下限。值为 1 表示不允许缩小。例如，值为 0.2 表示最大可缩小 80%。
archive (Archive) – 一个 Archive 对象，指向查找图像或非标准字体的位置。如果 text 引用图像或非标准字体，则此参数是必需的。如果 text 是 Story，则忽略此参数。
rotate (int) –
值可以是 0、90、180、270。根据此值，文本填充方向如下：
- 0：从左上角到右下角。
- 90：从左下角到右上角。
- 180：从右下角到左上角。
- 270：从右上角到左下角。
oc (int) – OCG / OCMD 的 xref，或 0。详情请参阅 Page.show_pdf_page()。
opacity (float) – 设置内容的填充和描边不透明度。仅考虑值 0 <= opacity < 1。
overlay (bool) – 将文本放在其他内容前面。详情请参阅 Page.show_pdf_page()。

返回:

一个浮点数元组 (spare_height, scale)。

spare_height：如果内容不适合，则为 -1，否则 >= 0。它是未使用的（仍可用）矩形条的高度。仅当 scale = 1 时（未发生缩小）为正。
scale：缩小因子，0 < scale <= 1。

请参阅本节食谱中的示例：如何使用 HTML 文本填充文本框。

显示/隐藏历史

v1.23.8 新增；仅基于。
v1.23.9 新增：opacity 参数。

绘制方法

draw_line(p1, p2, color=(0,), width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：从 p1 到 p2（point_like）绘制一条线。参见 Shape.draw_line()。

显示/隐藏历史

v1.18.4 修改

draw_zigzag(p1, p2, breadth=2, color=(0,), width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：从 p1 到 p2（point_like）绘制一条锯齿线。参见 Shape.draw_zigzag()。

显示/隐藏历史

v1.18.4 修改

draw_squiggle(p1, p2, breadth=2, color=(0,), width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：从 p1 到 p2（point_like）绘制一条波浪线。参见 Shape.draw_squiggle()。

显示/隐藏历史

v1.18.4 修改

draw_circle(center, radius, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：围绕 center（point_like）绘制一个半径为 radius 的圆。参见 Shape.draw_circle()。

显示/隐藏历史

v1.18.4 修改

draw_oval(quad, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：在给定的 rect_like 或 quad_like 内绘制一个椭圆。参见 Shape.draw_oval()。

显示/隐藏历史

v1.18.4 修改

draw_sector(center, point, angle, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, fullSector=True, overlay=True, closePath=False, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：绘制一个扇形区域，可选择将圆弧连接到圆心（像一块馅饼）。参见 Shape.draw_sector()。

显示/隐藏历史

v1.18.4 修改

draw_polyline(points, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：绘制由一系列 point_like 定义的多条相连的线段。参见 Shape.draw_polyline()。

显示/隐藏历史

v1.18.4 修改

draw_bezier(p1, p2, p3, p4, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：从 p1 到 p4 绘制三次贝塞尔曲线，控制点为 p2 和 p3（它们都是 point_like）。参见 Shape.draw_bezier()。

显示/隐藏历史

v1.18.4 修改

draw_curve(p1, p2, p3, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, closePath=False, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：这是 draw_bezier() 的一个特殊情况。参见 Shape.draw_curve()。

显示/隐藏历史

v1.18.4 修改

draw_rect(rect, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, radius=None, oc=0)#

仅限 PDF：绘制一个矩形。参见 Shape.draw_rect()。

显示/隐藏历史

v1.18.4 修改
v1.22.0 版本修改：添加了参数 radius。

draw_quad(quad, color=(0,), fill=None, width=1, dashes=None, lineCap=0, lineJoin=0, overlay=True, morph=None, stroke_opacity=1, fill_opacity=1, oc=0)#

仅限 PDF：绘制一个四边形。参见 Shape.draw_quad()。

显示/隐藏历史

v1.18.4 修改

insert_font(fontname='helv', fontfile=None, fontbuffer=None, set_simple=False, encoding=TEXT_ENCODING_LATIN)#

仅限 PDF：添加一个新字体，供文本输出方法使用，并返回其 xref。如果文件中尚不存在，则会添加字体定义。支持内置的 Base14_Fonts 和通过“保留”字体名称引用的 CJK 字体。字体也可以通过文件路径或包含字体文件镜像的内存区域提供。

参数:

fontname (str) –
该字体在此页面上输出文本时将被引用的名称。通常，您可以在此处“自由”选择（但请参阅 Adobe PDF References，第 16 页，第 7.3.5 节，以获取构建合法 PDF 名称的正式描述）。但是，如果它与 Base14_Fonts 或 CJK 字体之一匹配，则 fontfile 和 fontbuffer 将被忽略。

换句话说，您不能通过 fontfile / fontbuffer 插入字体，同时赋予它一个保留的 fontname。

注意

保留的字体名称可以以大写或小写的任何混合方式指定，仍然与正确的内置字体定义匹配：字体名称“helv”、“Helv”、“HELV”、“Helvetica”等都指向相同的字体定义“Helvetica”。但从 Page 的角度来看，它们是不同的引用。当您在同一页面上使用同一字体的不同 encoding 变体（拉丁语、西里尔语、希腊语）时，可以利用这一事实。
fontfile (str) – 字体文件的路径。如果使用此参数，则 fontname 必须与所有保留名称不同。
fontbuffer (bytes/bytearray) – 字体文件的内存镜像。如果使用此参数，则 fontname 必须与所有保留名称不同。此参数通常与 Font.buffer 一起使用，用于通过 Font 支持/可用的字体。
set_simple (int) – 仅适用于 fontfile / fontbuffer 的情况：强制将其视为“简单”字体，即仅使用字符编码不超过 255 的字体。
encoding (int) – 仅适用于“Helvetica”、“Courier”和“Times”系列的 Base14_Fonts。选择可用的编码之一：拉丁语（0）、西里尔语（2）或希腊语（1）。对于“Symbol”和“ZapfDingBats”，只能使用默认值（0 = 拉丁语）。

返回类型：

int

返回:

已安装字体的 xref。

注意

内置字体不会导致包含字体文件，因此生成的 PDF 文件将保持较小。但是，您的 PDF 查看器软件负责生成适当的外观——并且在如何或是否这样做方面存在差异。对于 CJK 字体尤其如此。Symbol 和 ZapfDingbats 在某些情况下也处理不正确。以下是字体名称及其对应的已安装基础字体名称

Base-14 字体 [1]

字体名称	已安装的基础字体	备注
helv	Helvetica	正常
heit	Helvetica-Oblique	斜体
hebo	Helvetica-Bold	粗体
hebi	Helvetica-BoldOblique	粗斜体
cour	Courier	正常
coit	Courier-Oblique	斜体
cobo	Courier-Bold	粗体
cobi	Courier-BoldOblique	粗斜体
tiro	Times-Roman	正常
tiit	Times-Italic	斜体
tibo	Times-Bold	粗体
tibi	Times-BoldItalic	粗斜体
symb	Symbol	[3]
zadb	ZapfDingbats	[3]

CJK 字体 [2] (中国, 日本, 韩国)

字体名称	已安装的基础字体	备注
china-s	Heiti	简体中文
china-ss	Song	简体中文 (衬线体)
china-t	Fangti	繁体中文
china-ts	Ming	繁体中文 (衬线体)
japan	Gothic	日语
japan-s	Mincho	日语 (衬线体)
korea	Dotum	韩语
korea-s	Batang	韩语 (衬线体)

insert_image(rect, *, alpha=-1, filename=None, height=0, keep_proportion=True, mask=None, oc=0, overlay=True, pixmap=None, rotate=0, stream=None, width=0, xref=0)#

仅限 PDF：将图像放入给定的矩形内。图像可以已存在于 PDF 中，也可以来自 pixmap、文件或内存区域。

参数:

rect (rect_like) – 放置图像的位置。必须是有限且非空的。
alpha (int) – 已废弃并忽略。
filename (str) – 图像文件名（MuPDF 支持的所有格式——参见支持的输入图像格式）。
height (int) –
keep_proportion (bool) – 保持图像的纵横比。
mask (bytes,bytearray,io.BytesIO) – 内存中的图像——用作基础图像的图像遮罩（alpha 值）。指定时，基础图像必须作为文件名或流提供，并且不得是已包含遮罩的图像。
oc (int) – (xref) 使图像可见性依赖于此 OCG 或 OCMD。多次插入时，首次插入后会被忽略。此属性存储在生成的 PDF 图像对象中，因此控制图像在整个 PDF 中的可见性。
overlay – 参见通用参数。
pixmap (Pixmap) – 包含图像的 pixmap。
rotate (int) – 旋转图像。必须是 90 度的整数倍。正值表示逆时针旋转。如果需要任意角度旋转，请考虑先将图像转换为 PDF（Document.convert_to_pdf()），然后改用 Page.show_pdf_page()。
stream (bytes,bytearray,io.BytesIO) – 内存中的图像（MuPDF 支持的所有格式——参见支持的输入图像格式）。
width (int) –
xref (int) – PDF 中已存在的图像的 xref。如果给定此参数，则忽略参数 filename、Pixmap、stream、alpha 和 mask。页面将仅接收对现有图像的引用。

返回:

嵌入图像的 xref。如果图像再次插入，这可以作为 xref 参数，极大地提升性能。

这个例子将同一个图像放在文档的每一页上

>>> doc = pymupdf.open(...)
>>> rect = pymupdf.Rect(0, 0, 50, 50)       # put thumbnail in upper left corner
>>> img = open("some.jpg", "rb").read()  # an image file
>>> img_xref = 0                         # first execution embeds the image
>>> for page in doc:
      img_xref = page.insert_image(rect, stream=img,
                 xref=img_xref,  2nd time reuses existing image
          )
>>> doc.save(...)

注意

该方法会检测同一图像的多次插入（如上述示例所示），并且仅在首次执行时存储其数据。即使使用默认值 xref=0，这一点也成立（尽管性能稍差）。
该方法无法检测到图像在打开文件之前是否已是文件的一部分。
您可以使用此方法为页面提供背景或前景图像，例如版权标志或水印。请记住，如果水印放在前景，则需要透明图像……
图像可能以未压缩的方式插入，例如使用 Pixmap 或图像具有 alpha 通道时。因此，在保存文件时考虑使用 deflate=True。此外，还有控制图像大小的方法——即使涉及透明度。请参阅如何将图像添加到 PDF 页面。
图像以其原始质量级别存储在 PDF 中。这可能远远优于您显示所需。在插入前考虑减小图像大小——例如，通过使用 pixmap 选项然后缩小或按比例缩小（参见 Pixmap 章）。PIL 方法 Image.thumbnail() 也可以用于此目的。文件大小的节省可能非常显著。
在多页上显示同一图像的另一种有效方法是使用另一个方法：show_pdf_page()。关于如何获取可用于此方法的中间 PDF，请参阅 Document.convert_to_pdf()。

显示/隐藏历史

v1.14.1 版本修改：默认情况下，图像保持其纵横比。
v1.14.11 版本修改：添加参数 keep_proportion、rotate。
v1.14.13 版本修改
- 图像现在总是居中放置在矩形中，即图像和矩形的中心是相同的。
- 添加了对 stream 作为 io.BytesIO 的支持。
v1.17.6 版本修改：插入矩形不再需要与页面的 Page.cropbox 有非空的交集 [5]。
v1.18.1 版本修改：添加了 mask 参数。
v1.18.3 版本修改：添加了 oc 参数。
v1.18.13 版本修改
- 允许将图像作为现有图像的 xref 提供。
- 添加了 xref 参数。
- 返回存储图像的 xref。
v1.19.3 版本修改：废弃并忽略 alpha 参数。

replace_image(xref, filename=None, pixmap=None, stream=None)#

将 xref 处的图像替换为另一个图像。

参数:

xref (int) – 图像的 xref。
filename – 新图像的文件名。
pixmap – 新图像的 Pixmap。
stream – 包含新图像的内存区域。

参数 filename、Pixmap、stream 的含义与 Page.insert_image() 相同，特别是必须提供其中一个且仅一个。

这是一项全局替换： 新图像将显示在文件中旧图像显示的所有位置。

此方法主要用于技术目的。典型用途包括将大图像替换为小版本，例如较低分辨率的灰度图像而非彩色图像，或更改透明度。

显示/隐藏历史

v1.21.0 新增

delete_image(xref)#

删除 xref 处的图像。这有点误导：实际上，图像被替换为一个小的透明 Pixmap，使用上面的 Page.replace_image()。但可见效果是等效的。

参数:: xref (int) – 图像的 xref。

这是一项全局替换： 旧图像显示在文件中的所有位置都将消失。

如果您通过 Page.get_images()、Page.get_image_info() 或 Page.get_text() 等方法检查/提取页面图像，替换的“虚拟”图像将被检测到，如下所示：(45, 47, 1, 1, 8, 'DeviceGray', '', 'Im1', 'FlateDecode')，并且似乎也“覆盖”了页面上的相同边界框。

显示/隐藏历史

v1.21.0 新增

get_text(option, *, clip=None, flags=None, textpage=None, sort=False, delimiters=None)#

以各种格式检索页面内容。根据 flags 值，这可能包括文本、图像和几种其他类型的对象。此方法是多个 TextPage 方法的包装器，通过选择输出选项 opt 如下：

“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()。可能包含文本和图像。
“rawjson” – TextPage.extractRAWJSON()。可能包含文本和图像。

参数:

opt (str) – 指示请求格式的字符串，可以是上述之一。支持大小写混合。如果拼写错误，将静默假定为选项“text”。
clip (rect-like) – 将提取限制在此矩形内。如果为 None（默认），则提取页面可见部分。未完全包含在 clip 中的任何内容（文本、图像）将被完全忽略。要完全避免剪裁，请使用 clip=pymupdf.INFINITE_RECT()。只有这样提取才会包含所有项。此参数对选项“html”、“xhtml”和“xml”无效。
flags (int) – 指示位，用于控制是否包含图像，或如何处理文本中的空白和 ligatures。有关可用指示位，请参见 Font Properties，有关默认设置，请参见文本提取标志默认值。(v1.16.2 新增)
textpage – 使用之前创建的 TextPage。这可以显著缩短执行时间：根据提取选项，可缩短 50% 以上，甚至高达 95%。如果指定此参数，则忽略“flags”和“clip”参数，因为它们是仅与 textpage 相关的属性。如果省略，将创建一个新的临时 textpage。
sort (bool) – 按垂直坐标，然后按水平坐标对输出进行排序。在许多情况下，这足以生成“自然”的阅读顺序。对 (X)HTML 和 XML 无效。对于选项“blocks”、“dict”、“json”、“rawdict”、“rawjson”，按各自块边界框的坐标 (y1, x0) 进行排序。对于选项“words”和“text”，文本行被完全重新合成以遵循文档中的阅读顺序和外观——这甚至在一定程度上重建了原始布局。
delimiters (str) – 在使用“words”输出选项时，使用这些字符作为附加单词分隔符（否则忽略）。默认情况下，所有空白字符（包括不间断空格 0xA0）都表示单词的开始和结束。现在您可以指定更多导致此行为的字符。例如，默认情况下 "john.doe@outlook.com" 将作为一个单词返回。如果您指定 delimiters="@."，则会返回四个单词 "john"、"doe"、"outlook"、"com"。其他可能的用途包括忽略标点符号字符 delimiters=string.punctuation。“单词”字符串将不包含任何分隔字符。(v1.23.5 中的新增功能)

返回类型:

str, list, dict

返回:

页面的内容，可以是字符串、列表或字典。有关详细信息，请参阅相应的 TextPage 方法。

注意

您可以使用此方法作为**文档转换工具**，将任何支持的文档类型转换为 TEXT、HTML、XHTML 或 XML 文档之一。
通过 *clip* 参数包含文本是按字符级别决定的：如果字符的 bbox 包含在 clip 中，则该字符将成为输出的一部分。这与密文注释中使用的算法**不同**：如果字符的 bbox 与任何密文注释**相交**，则该字符将被**移除**。

显示/隐藏历史

v1.19.0 中的更改：添加了 TextPage 参数
v1.19.1 中的更改：添加了 sort 参数
v1.19.6 中的更改：添加了用于按方法定义默认标志的新常量。
v1.23.5 中的更改：添加了 delimiters 参数
v1.24.11 中的更改：修改了 sort_True 对“text”和“words”的影响，使其更接近自然阅读顺序。

get_textbox(rect, textpage=None)#

检索矩形中包含的文本。

参数:

rect (*rect-like*) – 矩形类似对象。
textpage – 要使用的 TextPage。如果省略，将创建一个新的临时 textpage。

返回:

一个包含必要换行的字符串。它基于专用代码（在 v1.19.0 中更改）。典型用法是检查 Page.search_for() 的结果

>>> rl = page.search_for("currency:")
>>> page.get_textbox(rl[0])
'Currency:'
>>>

显示/隐藏历史

v1.17.7 中的新增功能
v1.19.0 中的更改：添加 TextPage 参数

get_textpage(clip=None, flags=3)#

为页面创建 TextPage。

参数:

flags (*int*) – 控制后续文本提取和搜索可用内容的指示位 – 请参阅 Page.get_text() 的参数。
clip (*rect-like*) – 将提取的文本限制在此区域。(v1.17.7 中的新增功能)

返回:

TextPage

显示/隐藏历史

v1.16.5 中的新增功能
v1.17.7 中的更改：引入了 clip 参数。

get_textpage_ocr(flags=3, language='eng', dpi=72, full=False, tessdata=None)#

**光学字符识别**（**OCR**）技术可用于提取页面中文本以栅格图像格式存在的文档中的文本数据。使用此方法对页面进行 **OCR** 以进行文本提取。

此方法返回一个包含 OCR 文本的页面的 TextPage。如果使用此方法，MuPDF 将调用 Tesseract-OCR。否则这是一个正常的 TextPage 对象。

参数:

flags (*int*) – 控制后续文本提取和搜索可用内容的指示位 – 请参阅 Page.get_text() 的参数。
language (*str*) – 期望的语言。如果期望多种语言，请使用“+”分隔的值，例如英语和西班牙语使用“eng+spa”。
dpi (*int*) – 期望的分辨率，以每英寸点数表示。影响识别质量（和执行时间）。
full (*bool*) – 是否对整页进行 OCR，或仅对显示的图像进行 OCR。
tessdata (*str*) – Tesseract 的语言支持文件夹 tessdata 的名称。如果省略，此信息必须以环境变量 TESSDATA_PREFIX 的形式存在。可通过函数 get_tessdata() 确定。

注意

此方法**不**支持 clip 参数 – OCR 始终针对完整的页面矩形进行。

返回:

一个 TextPage。执行时间可能显著长于 Page.get_textpage()。

对于整页 OCR，**所有文本**将使用 Tesseract 的“GlyphlessFont”字体。在部分 OCR 的情况下，正常文本将保留其属性，只有来自图像的文本将使用 GlyphlessFont。

注意

**OCRed 文本仅当** PyMuPDF 的文本提取和搜索方法中指定的 TextPage 参数是此方法的输出时才可用。

此 Jupyter notebook 提供了一个使用 OCR textpage 的示例。

显示/隐藏历史

v.1.19.0 中的新增功能
v1.19.1 中的更改：支持整页和部分页面的 OCR。

get_drawings(extended=False)#

返回页面的矢量图形。这些是绘制线条、矩形、四边形或曲线的指令，包括颜色、透明度、线宽和虚线样式等属性。备用术语包括“线条艺术”和“绘图”。

返回:: 一个字典列表。列表中的每个字典项包含一个或多个相关的绘制命令：它们具有相同的属性（颜色、虚线样式等）。在 PDF 中这被称为**“路径”**，因此我们在此采用了该名称，但此方法**适用于所有文档类型**。

填充、描边和填充描边路径的路径字典设计为与类 Shape 兼容。包含以下键

键	值
closePath	与 Shape 中的参数相同。
color	描边颜色（参见 Shape）。
dashes	虚线规格（参见 Shape）。
even_odd	区域重叠的填充颜色 – 与 Shape 中的参数相同。
fill	填充颜色（参见 Shape）。
items	绘制命令列表：线条、矩形、四边形或曲线。
lineCap	数字 3 元组，在与 Shape 一起输出时使用其最大值。
lineJoin	与 Shape 中的参数相同。
fill_opacity	填充颜色透明度（参见 Shape）。(v1.18.17 中的新增功能)
stroke_opacity	描边颜色透明度（参见 Shape）。(v1.18.17 中的新增功能)
rect	此路径覆盖的页面区域。仅供参考。
layer	适用的可选内容组的名称。(v1.22.0 中的新增功能)
level	如果 `extended=True`，则表示层级级别。(v1.22.0 中的新增功能)
seqno	构建页面外观时的命令编号。(v1.19.0 中的新增功能)
type	此路径的类型。(v1.18.17 中的新增功能)
width	描边线宽。（参见 Shape）。

键 "opacity" 已被新键 "fill_opacity" 和 "stroke_opacity" 替换。这现在与 Shape.finish() 的相应参数兼容。(v1.18.17 中的更改)

对于组或裁剪之外的路径，键 "type" 采用以下值之一

**“f”** – 这是**仅填充**路径。只有与此操作相关的键值才有意义，不适用的键值会以 None 的值存在："color"、"lineCap"、"lineJoin"、"width"、"closePath"、"dashes"，应忽略。
**“s”** – 这是**仅描边**路径。与前一个类似，键 "fill" 会以 None 的值存在。
**“fs”** – 这是执行组合**填充**和**描边**操作的路径。

path["items"] 中的每个项是以下之一

("l", p1, p2) - 从 p1 到 p2 的直线（Point 对象）。
("c", p1, p2, p3, p4) - **从 p1 到 p4** 的三次贝塞尔曲线（p2 和 p3 是控制点）。所有对象类型均为 Point。
("re", rect, orientation) - 一个 Rect。现在可以检测到同一路径中的多个矩形（v1.18.17 中的更改）。整数 orientation 分别为 1 和 -1，指示封闭区域是否向左（1 = 逆时针）或向右旋转 [7]（v1.19.2 中的更改）。
("qu", quad) - 一个 Quad。检测到 3 或 4 条连续的线实际表示一个 Quad（v1.19.2 中的更改）。(v1.18.17 中的新增功能)

在正常、不太复杂的情况下，使用类 Shape，您应该能够在单独的（PDF）页面上高度保真地重新创建原始绘图。请参阅以下关于限制的注释。编码草稿可在如何提取绘图中找到。

指定 extended=True 会显著改变输出。最重要的是，新增了字典类型：“clip”和“group”。所有路径现在将组织在一个分层结构中，由新的整数键“level”（层级级别）编码。每个组或裁剪建立一个新的层级，适用于所有后续具有*更大* level 值的路径。(v1.22.0 中的新增功能)

任何 level 值小于其前驱的路径将结束（至少）前一个层级的范围。具有与前一个裁剪相同 level 的“clip”路径将结束该裁剪的范围。组也同样适用。这通过一个例子最好解释

+------+------+--------+------+--------+
| line | lvl0 | lvl1   | lvl2 |  lvl3  |
+------+------+--------+------+--------+
|  0   | clip |        |      |        |
|  1   |      | fill   |      |        |
|  2   |      | group  |      |        |
|  3   |      |        | clip |        |
|  4   |      |        |      | stroke |
|  5   |      |        | fill |        |  ends scope of clip in line 3
|  6   |      | stroke |      |        |  ends scope of group in line 2
|  7   |      | clip   |      |        |
|  8   | fill |        |      |        |  ends scope of line 0
+------+------+--------+------+--------+

第 0 行的 clip 适用于包括第 7 行在内的行。第 2 行的 Group 适用于第 3 到 5 行，第 3 行的 clip 仅适用于第 4 行。

第 4 行的“stroke”受第 2 行的“group”和第 3 行的“clip”控制（后者又是第 0 行 clip 的子集）。

**“clip”** 字典。只要后续字典具有**更大“level”**值，其值（最重要的是“scissor”）就保持有效/适用。

键	值
closePath	与“stroke”或“fill”字典中的相同
even_odd	与“stroke”或“fill”字典中的相同
items	与“stroke”或“fill”字典中的相同
rect	与“stroke”或“fill”字典中的相同
layer	与“stroke”或“fill”字典中的相同
level	与“stroke”或“fill”字典中的相同
scissor	裁剪矩形
type	“clip”

“group”字典。只要后续字典具有**更大“level”**值，其值就保持有效（适用）。任何 level 等于或低于此 level 的字典都会结束此组。

键	值
rect	与“stroke”或“fill”字典中的相同
layer	与“stroke”或“fill”字典中的相同
level	与“stroke”或“fill”字典中的相同
isolated	(布尔值) 此组是否隔离
knockout	(布尔值) 这是否是“Knockout Group”
blendmode	混合模式的名称，默认为“Normal”
opacity	范围 [0, 1] 内的浮点值。
type	“group”

注意

此方法基于 Page.get_cdrawings() 的输出 – 后者速度快得多，但处理其输出需要更多一些关注。

显示/隐藏历史

v1.18.0 中的新增功能
v1.18.17 中的更改
v1.19.0 中的更改：添加“seqno”键，移除“clippings”键
v1.19.1 中的更改：“color” / “fill”键现在始终是 RGB 元组或 None。这解决了由特殊颜色空间引起的问题。
v1.19.2 中的更改：为“re”项覆盖区域的*“方向”*添加了指示器。
v1.22.0 中的更改：添加新键 "layer"，其中包含路径的可选内容组的名称（或 None）。
v1.22.0 中的更改：添加参数 extended 以同时返回裁剪和组路径。

get_cdrawings(extended=False)#

提取页面上的矢量图形。除了以下技术差异外，功能上等同于 Page.get_drawings()，但速度快得多

每种路径类型仅包含相关的键，例如描边路径没有 "fill" 颜色键。请参见方法 Page.get_drawings() 中的注释。
坐标以 point_like、rect_like 和 quad_like 的**元组**形式给出 – 而非 Point、Rect、Quad 对象。

如果性能是您的关注点，请考虑使用此方法：与早于 1.18.17 的版本相比，您应该会看到响应时间大大缩短。我们曾见过页面需要 2 秒来处理，现在使用此方法只需 200 毫秒。

显示/隐藏历史

v1.18.17 中的新增功能
v1.19.0 中的更改：移除了“clippings”键，添加了“seqno”键。
v1.19.1 中的更改：始终生成 RGB 颜色元组。
v1.22.0 中的更改：添加新键 "layer"，其中包含路径的可选内容组的名称（或 None）。
v1.22.0 中的更改：添加了参数 extended 以同时返回裁剪路径。

get_fonts(full=False)#: 仅限 PDF：返回页面引用的字体列表。Document.get_page_fonts() 的包装器。

get_images(full=False)#: 仅限 PDF：返回页面引用的图像列表。Document.get_page_images() 的包装器。

get_image_info(hashes=False, xrefs=False)#

返回页面显示的所有图像的元信息字典列表。这适用于所有文档类型。

参数:

hashes (*bool*) – 计算遇到的每个图像的 MD5 哈希码，这有助于识别重复图像。这会向输出添加键 "digest"，其值是一个 16 字节的 bytes 对象。(v1.18.13 中的新增功能)
xrefs (*bool*) – **仅限 PDF。** 尝试查找每个图像的 xref。暗示 hashes=True。向字典添加 "xref" 键。如果找不到，值为 0，这意味着图像是“内嵌”的，或者由于某种原因无法检测到其 xref。请注意，此选项会延长响应时间，因为对于每个带有 xref 的图像，MD5 哈希码将至少计算两次。(v1.18.13 中的新增功能)

返回类型:

list[dict]

返回:

一个字典列表。这包含**恰好显示在页面上的**图像的信息 – 包括*“内嵌图像”*。字典布局类似于 page.get_text("dict") 中图像块的布局。

与 Page.get_text() 中包含的图像不同，此方法不加载图像的**二进制内容**，这显著减少了内存使用。另一个区别是图像检测不受页面可见部分或任何 clip 参数的限制：方法 Page.get_text() 只会提取完全**包含**在提供的 clip 中的图像。

键	值
number	块编号 (`int`)
bbox	页面上的图像 bbox，`rect_like`
width	width
原始图像宽度 (`int`)	height
原始图像高度 (`int`)	cs-name
颜色空间名称 (`str`)	colorspace
colorspace.n (`int`)	xres
x 方向分辨率 (`int`) [10]	yres
y 方向分辨率 (`int`) [10]	bpc
每组件位数 (`int`)	size
图像占用的存储空间 (`int`)	digest
MD5 哈希码 (bytes`)，如果 `hashes 为 true	xref
图像 `xref` 或 0，如果 xrefs 为 true	transform
将图像矩形转换为 bbox 的矩阵，`matrix_like`	has-mask

图像是否透明并带有遮罩 (bool)

显示/隐藏历史

总是报告同一图像的多次出现。您可以通过比较它们的 digest 值来检测重复项。
v1.18.11 中的新增功能

v1.18.13 中的更改：添加了图像 MD5 哈希码计算和 xref 搜索。: get_xobjects()#

仅限 PDF：返回页面引用的 Form XObjects 列表。Document.get_page_xobjects() 的包装器。

get_image_rects(item, transform=False)#

仅限 PDF：返回嵌入图像的边界框和变换矩阵。这是 Page.get_image_bbox() 的改进版本，具有以下差异
对图像**如何**被调用（由页面或其 Form XObjects 之一调用）没有限制。结果总是完整和正确的。
结果是 Rect 或 (Rect, Matrix) 对象列表 – 取决于 *transform*。列表中的每个项表示图像在页面上的一个位置。Page.get_image_bbox() 可能无法检测到多次出现。

参数:

此方法调用 Page.get_image_info() 并设置 xrefs=True，因此响应时间比 Page.get_image_bbox() 长很多。
item (*list*, *str*, *int*) – Page.get_images() 列表中的一个项，或者此类项的引用**名称**条目 (item[7])，或者图像的 xref。

返回类型:

列表

返回:

transform (*bool*) – 同时返回用于将图像矩形变换到页面上 bbox 的矩阵。如果为 true，则返回元组 (bbox, matrix)。

显示/隐藏历史

页面上每个图像出现位置的边界框和相应的变换矩阵。如果该项不在页面上，则返回一个空列表 []。

v1.18.13 中的新增功能

get_image_bbox(item, transform=False)#

参数:

仅限 PDF：返回嵌入图像的边界框和变换矩阵。
item (*list*, *str*) – Page.get_images() 列表中指定了 *full=True* 的一个项，或者此类项的引用**名称**条目，即 item[-3]（或 item[7]）。

返回类型:

transform (*bool*) – 返回用于将图像矩形变换到页面上 bbox 的矩阵 (v1.18.11 中的新增功能)。默认只返回 bbox。如果为 true，则返回元组 (bbox, matrix)。

返回:

Rect 或 (Rect, Matrix)

显示/隐藏历史

图像的边界框 – 可选地也返回其变换矩阵。
(v1.16.7 中的更改): 如果页面实际上没有显示此图像，现在将返回一个无限矩形。在以前的版本中，会引发异常。形式上无效的参数仍然会引发异常。
(v1.17.0 中的更改): 只考虑页面直接引用的图像。这意味着嵌入 PDF 页面中出现的图像将被忽略并引发异常。
(v1.18.5 中的更改): 移除了 v1.17.0 中引入的限制：可以指定页面图像列表的任何项。
(v1.18.11 中的更改): 部分恢复了限制：只考虑页面直接引用或页面直接引用的 Form XObject 引用的图像。

注意

(v1.18.11 中的更改): 可选地也将变换矩阵与 bbox 一起作为元组 (bbox, transform) 返回。
请注意，Page.get_images() 可能包含“死”条目，即页面**未显示的**图像。这不是错误，而是 PDF 创建者有意为之。在这种情况下不会引发异常，而是返回一个无限矩形。在使用此方法之前执行 Page.clean_contents() 可以避免这种情况。

显示/隐藏历史

图像的“变换矩阵”定义为满足表达式 bbox / transform == pymupdf.Rect(0, 0, 1, 1) 为 true 的矩阵，详细信息请参阅此处：图像变换矩阵。

v1.18.11 中的更改：返回图像变换矩阵

get_svg_image(matrix=pymupdf.Identity, text_as_path=True)#

参数:

从页面创建 SVG 图像。当前仅支持整页图像。
matrix (*matrix_like*) – 一个矩阵，默认为 Identity。

返回:

text_as_path (*bool*) – – 控制文本如何表示。True 将每个字符作为一系列基本绘制命令输出，这会导致在浏览器中显示文本更精确，但对于以文本为主的页面来说，输出会**大得多**。False 的显示质量取决于当前系统上是否存在引用的字体。对于缺失的字体，互联网浏览器将回退到某个默认字体 – 导致显示效果不佳。如果您想解析 SVG 中的文本，请选择 False。(v1.17.5 中的新增功能)

注意

一个包含图像的 UTF-8 编码字符串。由于 SVG 具有 XML 语法，它可以保存在文本文件中，标准扩展名是 .svg。

对于 PDF，您可以通过在使用此方法之前修改页面的 CropBox 来规避“仅限整页图像”的限制。

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

从页面创建 pixmap。这可能是创建 Pixmap 最常用的方法。

参数:

所有参数都**仅限关键字**。
matrix (*matrix_like*) – 默认为 Identity。
dpi (*int*) – x 和 y 方向的期望分辨率。如果不是 None，则忽略 "matrix" 参数。(v1.19.2 中的新增功能)
colorspace (str 或 Colorspace) – 期望的颜色空间，可以是“GRAY”、“RGB”或“CMYK”（不区分大小写）。或者指定一个 Colorspace，即预定义颜色空间之一：csGRAY、csRGB 或 csCMYK。
clip (*irect_like*) – 将渲染限制在此区域与页面矩形的交集范围内。
alpha (*bool*) –
显示/隐藏历史
是否添加 alpha 通道。如果您不是确实需要透明度，请始终接受默认值 False。这将节省大量内存（对于 RGB 来说是 25%……并且 pixmap 通常都**很大**！），并且也节省处理时间。另请注意图像渲染方式的**重要区别**：使用 True 时，pixmap 的样本区域将预先使用 *0x00* 清除。这会在页面为空白的地方产生**透明**区域。使用 False 时，pixmap 的样本将预先使用 *0xff* 清除。这会在页面没有内容显示的地方产生**白色**。
v1.14.17 中的更改

默认 alpha 值现在是 False。

使用 *alpha=True* 生成
使用 *alpha=False* 生成

返回类型:

Pixmap

返回:

annots (*bool*) – *(v1.16.0 中新增)* 是否也渲染注释或抑制它们。您可以单独为注释创建 pixmap。

注意

页面的 Pixmap。为了精细控制生成的图像，最重要的参数是 **matrix**。例如，您可以使用 **Matrix(xzoom, yzoom)** 增加或减少图像分辨率。如果 zoom > 1，您将获得更高的分辨率：zoom=2 将使该方向的像素数量加倍，从而生成 2 倍大的图像。非正值将分别水平翻转或垂直翻转。类似地，矩阵还允许您旋转或剪切，并且您可以通过矩阵乘法等方式组合效果。有关详细信息，请参见 Matrix 部分。

如果 alpha=True，pixmap 将具有*“预乘”*像素。要了解一些背景知识，例如在此处查找“Premultiplied alpha”：此处。

In [1]: import pymupdf
In [2]: doc=pymupdf.open("demo1.pdf")
In [3]: page=doc[0]
In [4]: rotation = page.rotation
In [5]: cropbox = page.cropbox
In [6]: page.set_cropbox(page.mediabox)
In [7]: page.set_rotation(0)
In [8]: pix = page.get_pixmap()
In [9]: page.set_cropbox(cropbox)
In [10]: if rotation != 0:
   ...:     page.set_rotation(rotation)
   ...:
In [11]:

显示/隐藏历史

此方法将遵守任何页面旋转，并且不会超出 clip 与 Page.cropbox 的交集。如果您需要页面的 mediabox（并且这是一个不同的矩形），您可以使用以下代码片段来实现：

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

annot_names()#

返回类型:: 列表

显示/隐藏历史

仅限 PDF：返回注释、控件和链接的名称列表。从技术上讲，这些是页面 */Annots* 数组中找到的每个 PDF 对象的 */NM* 值。

v1.16.10 中的新增功能

annot_xrefs()#

返回类型:: 列表
返回:: 仅限 PDF：返回注释、控件和链接的 xref 号码列表 – 从技术上讲是页面 */Annots* 数组中找到的所有条目。

显示/隐藏历史

一个 *(xref, type)* 项列表，其中 type 是注释类型。使用类型区分链接、字段和注释，参见注释类型。

v1.17.1 中的新增功能

load_annot(ident)#

参数:: 仅限 PDF：返回由 *ident* 标识的注释。这可以是其唯一名称（PDF /NM 键），或其 xref。
返回类型:: Annot
返回:: ident (*str*, *int*) – 注释名称或 xref。

注意

注释或 None。

显示/隐藏历史

一个 *(xref, type)* 项列表，其中 type 是注释类型。使用类型区分链接、字段和注释，参见注释类型。

方法 Page.annot_names() 和 Page.annot_xrefs() 分别提供了名称列表或 xref 列表，可以从中选取项目并通过此方法加载。

load_widget(xref)#

参数:: 仅限 PDF：返回由 xref 标识的字段。
返回类型:: Widget
返回:: xref (*int*) – 字段的 xref。

注意

字段或 None。

显示/隐藏历史

这类似于类似的方法 Page.load_annot() – 只是在此处仅支持 xref 作为标识符。

v1.19.6 中的新增功能

load_links()#

返回类型:: Link
返回:: 返回页面上的第一个链接。first_link 属性的同义词。

页面上的第一个链接（或 None）。

set_rotation(rotate)#

参数:: 仅限 PDF：设置页面的旋转。

rotate (*int*) – 一个整数，指定所需的旋转角度（以度为单位）。必须是 90 的整数倍。值将被转换为 0、90、180、270 之一。

recolor(components=1)#

参数:: 仅限 PDF：更改页面上所有对象的颜色空间组件。

components (*int*) – 期望的颜色组件数量。必须是 1、3 或 4 之一，分别对应颜色空间 DeviceGray、DeviceRGB 或 DeviceCMYK。此方法影响文本、图像和矢量图形。例如，使用默认值 1，页面将被转换为灰度。如果页面已经是灰度的，此方法不会引起可见的变化 – 与 components 的值无关。

这些更改是**永久性的**，无法恢复。

remove_rotation()#

返回:

仅限 PDF：在保持外观和页面内容的同时，将页面旋转设置为 0。

用于实现此更改的逆矩阵。如果页面未旋转（旋转 0），则返回 Identity。此方法自动重新计算页面上存在的任何注释、链接和控件的矩形。

例如，当与 Page.show_pdf_page() 一起使用时，此方法可能会派上用场。

show_pdf_page(rect, docsrc, pno=0, keep_proportion=True, overlay=True, oc=0, rotate=0, clip=None)#

仅限 PDF：将另一个 PDF 的页面显示为**矢量图像**（否则类似于 Page.insert_image()）。这是一种多用途方法。例如，您可以使用它来
创建现有 PDF 文件的“n-up”版本，将多个输入页面合并到**一个输出页面**中（参见示例 combine.py），
创建“海报化”的 PDF 文件，即将每个输入页面分割成多个部分，每个部分创建一个独立的输出页面（参见 posterize.py），

参数:

包含基于 PDF 的矢量图像，如公司标志、水印等，参见 svg-logo.py，它在每个页面上放置一个基于 SVG 的标志（需要额外的包来处理 SVG 到 PDF 的转换）。
rect (*rect_like*) – 在当前页面上放置图像的位置。必须是有限的，并且其与页面的交集不能为空。
docsrc (Document) – 包含页面的源 PDF 文档。必须是不同的文档对象，但可以是同一个文件。
pno (*int*) – 要显示的页码（从 0 开始，范围在 -∞ < pno < docsrc.page_count）。
keep_proportion (*bool*) – 是否保持宽高比（默认）。如果为 false，无论旋转值如何，所有 4 个角始终位于目标矩形的边界上。通常，这将导致图像失真和/或非矩形。
overlay (*bool*) – 将图像放在前景（默认）或背景。
oc (*int*) – (xref) 使可见性取决于此 OCG / OCMD（必须在目标 PDF 中定义）[9]。(v1.18.3 中的新增功能)
rotate (*float*) – 以某个角度旋转显示源矩形。支持任何角度（v1.14.11 中的更改）。(v1.14.10 中的新增功能)

注意

clip (*rect_like*) – 选择要显示的源页面的哪个部分。默认为整页，否则必须是有限的，并且其与源页面的交集不能为空。

与方法 Document.insert_pdf() 不同，此方法不复制注释、控件或链接，因此目标中不包含这些 [6]。但它所有**其他资源（文本、图像、字体等）**将被导入当前 PDF。因此，它们将出现在文本提取以及 get_fonts() 和 get_images() 列表中 – 即使它们不包含在 *clip* 给定的可见区域中。

>>> doc = pymupdf.open()  # new empty PDF
>>> page=doc.new_page()  # new page in A4 format
>>>
>>> # upper half page
>>> r1 = pymupdf.Rect(0, 0, page.rect.width, page.rect.height/2)
>>>
>>> # lower half page
>>> r2 = r1 + (0, page.rect.height/2, 0, page.rect.height/2)
>>>
>>> src = pymupdf.open("PyMuPDF.pdf")  # show page 0 of this
>>>
>>> page.show_pdf_page(r1, src, 0, rotate=90)
>>> page.show_pdf_page(r2, src, 0, rotate=-90)
>>> doc.save("show.pdf")

显示/隐藏历史

示例：显示同一源页面，旋转 90 度和 -90 度
v1.14.11 中的更改：参数 *reuse_xref* 已弃用。将源矩形居中放置在目标矩形中。现在支持任何旋转角度。

v1.18.3 中的更改：新增参数 oc。

new_shape()#

返回类型:: Shape
返回:: 仅限 PDF：为页面创建新的 Shape 对象。

一个新的 Shape，用于复合绘图。请参见那里的描述。

search_for(needle, *, clip=None, quads=False, flags=TEXT_DEHYPHENATE | TEXT_PRESERVE_WHITESPACE | TEXT_PRESERVE_LIGATURES | TEXT_MEDIABOX_CLIP, textpage=None)#

参数:

在页面上搜索 *needle*。TextPage.search() 的包装器。
needle (*str*) – 要搜索的文本。可以包含空格。忽略大小写，但仅对 ASCII 字符有效：例如，如果 needle 是“compétences”，则找不到“COMPÉTENCES” – 但“compÉtences”可以找到。对于德语元音变音等也同样适用。
clip (*rect_like*) – 只在此区域内搜索。(v1.18.2 中的新增功能)
quads (*bool*) – 返回对象类型 Quad 而非 Rect。
flags (*int*) – 控制底层 TextPage 提取的数据。默认情况下，连字和空白字符保留，并检测到连字符 [8]。

返回类型:

列表

返回:

textpage – 使用之前创建的 TextPage。这会**显著**减少执行时间。如果指定，则忽略“flags”和“clip”参数。如果省略，将创建一个临时 textpage。(v1.19.0 中的新增功能)

显示/隐藏历史

一个 Rect 或 Quad 对象列表，每个对象 – **通常！** – 围绕一个 *needle* 的出现位置。**然而：**如果 *needle* 的部分出现在多行上，则为每个部分生成一个单独的项。因此，如果 needle = "search string"，可能会生成两个矩形。

v1.18.2 中的更改
列表长度不再有限制（移除了 hit_max 参数）。

注意

如果单词在行末**连字符断开**，仍然可以找到它。例如，即使“method”在行末以“meth-od”的形式断开，仍然可以找到 needle “method”，并返回两个矩形：一个围绕“meth”（不带连字符），另一个围绕“od”。

注意

此方法支持多行文本标记注释：您可以将返回的完整列表作为创建注释的**单个**参数使用。
有一个棘手的方面：搜索逻辑将 *needle* 的**连续多次出现**视为一个：假设 *needle* 是“abc”，页面包含“abc”和“abcabc”，那么将只返回**两个**矩形，一个用于“abc”，第二个用于“abcabc”。

注意

您始终可以使用 Page.get_textbox() 来检查每个矩形实际围绕的文本。

>>> pattern = re.compile(r"...")  # the regex pattern
>>> words = page.get_text("words")  # extract words on page
>>> matches = [w for w in words if pattern.search(w[4])]

一个经常被要求的功能是支持在指定 "needle" 字符串时使用**正则表达式**：**目前无法做到这一点。**如果您需要这方面的功能，请首先以所需的格式提取文本，然后通过匹配某个正则表达式模式来筛选结果。以下是匹配单词的示例

显示/隐藏历史

在 v1.18.2 中更改：添加了 clip 参数。移除 hit_max 参数。添加默认值 “dehyphenate”。
matches 列表将包含与给定模式匹配的单词。同样，您可以从 page.get_text("dict") 的输出中选择 span["text"]。

v1.18.2 中的更改：添加了 clip 参数。移除了 hit_max 参数。添加了默认的“dehyphenate”。

v1.19.0 中的更改：添加了 TextPage 参数。

参数:: set_mediabox(r)#

注意

仅限 PDF：通过在页面对象定义中设置 mediabox 来更改页面的物理尺寸。

注意

r (*rect-like*) – 新的 mediabox 值。

显示/隐藏历史

此方法还会移除页面的其他（可选）矩形（cropbox、ArtBox、TrimBox 和 Bleedbox），以防止出现不一致的情况。这将导致它们采用其默认值。
对于非空页面，这可能会产生不良影响，因为所有内容的位置都取决于此值，从而改变位置甚至消失。

v1.16.13 中的新增功能

v1.19.4 中的更改：移除所有其他矩形定义。

参数:: set_cropbox(r)#

仅限 PDF：更改页面的可见部分。

>>> page = doc.new_page()
>>> page.rect
pymupdf.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> page.cropbox  # cropbox and mediabox still equal
pymupdf.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> # now set cropbox to a part of the page
>>> page.set_cropbox(pymupdf.Rect(100, 100, 400, 400))
>>> # this will also change the "rect" property:
>>> page.rect
pymupdf.Rect(0.0, 0.0, 300.0, 300.0)
>>>
>>> # but mediabox remains unaffected
>>> page.mediabox
pymupdf.Rect(0.0, 0.0, 595.0, 842.0)
>>>
>>> # revert CropBox change
>>> # either set it to MediaBox
>>> page.set_cropbox(page.mediabox)
>>> # or 'refresh' MediaBox: will remove all other rectangles
>>> page.set_mediabox(page.mediabox)

r (*rect_like*) – 页面的新可见区域。请注意，这**必须**以**未旋转坐标**指定，不得为空、不得为无限，并且必须完全包含在 Page.mediabox 中。

执行后**（如果页面未旋转）**，Page.rect 将等于此矩形，必要时会移至左上角位置 (0, 0)。示例会话

set_artbox(r)#

set_bleedbox(r)#

显示/隐藏历史

set_trimbox(r)#

仅限 PDF：在页面对象中设置相应的矩形。这些对象的含义请参见 Adobe PDF 参考手册，第 77 页。参数和限制与 Page.set_cropbox() 相同。

v1.19.4 中的新增功能

rotation#

包含页面的旋转角度（对于非 PDF 类型始终为 0）。这是 PDF 文件中该值的一个副本。PDF 文档中提到

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: int

在 PyMuPDF 中，我们确保此属性始终是 0、90、180 或 270 之一。

类型：

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Point

cropbox_position#

包含 PDF 页面 /CropBox 的左上角点，否则为 *Point(0, 0)*。

注意

cropbox#

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Rect

PDF 页面的 /CropBox。总是返回**未旋转的**页面矩形。对于非 PDF 文件，这始终等于页面矩形。

在 PDF 中，`/MediaBox`、`/CropBox` 与页面矩形之间的关系有时可能令人困惑，请查阅 MediaBox 的术语表。

artbox#

分别是页面的 /ArtBox、/BleedBox、/TrimBox。如果未提供，默认为 Page.cropbox。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Rect

mediabox_size#

对于 PDF，包含页面的 Page.mediabox 的宽度和高度；否则，包含 Page.rect 的右下角坐标。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Point

mediabox#

对于 PDF，页面的 mediabox；否则为 Page.rect。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Rect

注意

对于大多数 PDF 文档和对于 所有其他文档类型，page.rect == page.cropbox == page.mediabox 为真。然而，对于某些 PDF，可见页面是 mediabox 的真子集。此外，如果页面被旋转，其 Page.rect 可能不等于 Page.cropbox。在这些情况下，上述属性有助于正确确定页面元素的位置。

transformation_matrix#

该矩阵将坐标从 PDF 空间转换为 MuPDF 空间。例如，在 PDF /Rect [x0 y0 x1 y1] 中，坐标对 (x0, y0) 指定矩形的左下角点——与 MuPDF 的系统形成对比，在 MuPDF 系统中 (x0, y0) 指定左上角。将 PDF 坐标与此矩阵相乘将得到 (Py-) MuPDF 矩形版本。显然，逆矩阵将再次得到 PDF 矩形。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Matrix

rotation_matrix#

derotation_matrix#

这些矩阵可用于处理旋转的 PDF 页面。当向 PDF 页面添加/插入任何内容时，始终使用未旋转页面的坐标。这些矩阵有助于在两种状态之间进行转换。示例：如果页面旋转了 90 度——那么 A4 页面的左上角 Point(0, 0) 的坐标会是什么？

>>> page.set_rotation(90)  # rotate an ISO A4 page
>>> page.rect
Rect(0.0, 0.0, 842.0, 595.0)
>>> p = pymupdf.Point(0, 0)  # where did top-left point land?
>>> p * page.rotation_matrix
Point(842.0, 0.0)
>>>

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Matrix

first_link#

包含页面的第一个 Link (或 None)。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Link

first_annot#

包含页面的第一个 Annot (或 None)。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Annot

first_widget#

包含页面的第一个 Widget (或 None)。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Widget

number#

页码。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: int

parent#

所属的文档对象。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Document

rect#

包含页面的矩形。与 Page.bound() 的结果相同。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Rect

xref#

页面的 PDF xref。如果不是 PDF，则为零。

“显示或打印页面时应顺时针旋转的度数。值必须是 90 的倍数。默认值：0。”: Rect

get_links() 条目描述#

Page.get_links() 列表中的每个条目都是一个字典，包含以下键

kind: (必需) 指示链接类型的整数。这是 LINK_NONE、LINK_GOTO、LINK_GOTOR、LINK_LAUNCH 或 LINK_URI 之一。有关这些名称的值和含义，请参阅 Link Destination Kinds。
from: (必需) 一个 Rect，描述页面可见表示上的“热点”位置（通常是光标变成手形图像的地方）。
page: 指示目标页面的 0-based 整数。LINK_GOTO 和 LINK_GOTOR 必需，否则忽略。
to: 要么是一个 pymupdf.Point，指定给定页面上的目标位置，默认为 pymupdf.Point(0, 0)；要么是一个符号（间接）名称。如果指定了间接名称，则需要 page = -1，并且该名称必须在 PDF 中定义才能生效。LINK_GOTO 和 LINK_GOTOR 必需，否则忽略。
file: 指定目标文件的字符串。LINK_GOTOR 和 LINK_LAUNCH 必需，否则忽略。
uri: 指定目标互联网资源的字符串。LINK_URI 必需，否则忽略。您应该确保此字符串以一个明确的子字符串开头，该子字符串对 URL 的子类型进行分类，例如 "http://"、"https://"、"file://"、"ftp://"、"mailto:" 等。否则您的浏览器将尝试解释文本并对预期的 URL 类型得出不想要/意料之外的结论。
xref: 指定链接对象的 PDF xref 的整数。切勿以任何方式更改此条目。链接删除和更新必需，否则忽略。对于非 PDF 文档，此条目包含 -1。如果 MuPDF 不支持任何链接 - 请参阅关于支持链接的注意事项，则 get_links() 列表中的所有条目也为 -1。

关于支持链接的注意事项#

MuPDF 对链接的支持在 v1.10a 中有所改变。这些更改影响链接类型 LINK_GOTO 和 LINK_GOTOR。

读取（与 get_links() 方法和 first_link 属性链相关）#

如果 MuPDF 检测到指向另一个文件的链接，它将提供 LINK_GOTOR 或 LINK_LAUNCH 链接类型。对于 LINK_GOTOR 的情况，目标详情可以作为页码（可能包含位置信息）给出，也可以作为间接目标给出。

如果给出了间接目标，则这由 page = -1 指示，并且 link.dest.dest 将包含此名称。get_links() 列表中的字典将把此信息作为 to 值。

内部链接总是属于 LINK_GOTO 类型。如果内部链接指定了间接目标，它将始终被解析，并且将返回解析后的直接目标。内部链接永远不会返回名称，并且未定义的目标将导致链接被忽略。

写入#

PyMuPDF 通过构造和写入相应的 PDF 对象源来写入（更新、插入）链接。这使得为 LINK_GOTOR 和 LINK_GOTO 链接类型指定间接目标成为可能（不支持 PDF 1.2 之前的文件格式）。

警告

如果一个 LINK_GOTO 间接目标指定了一个未定义的名称，这个链接随后无法通过 MuPDF / PyMuPDF 找到/再次读取。然而，其他阅读器将检测到它，但会将其标记为错误。

间接的 LINK_GOTOR 目标通常当然无法检查其有效性，因此总是被接受。

示例：如何插入指向同一文档中另一页的链接

确定当前页面上应放置链接的矩形区域。这可能是图像或某些文本的边界框。
确定目标页码（“pno”，0-based）以及其上的一个 Point，链接应指向该点。
创建一个字典 d = {"kind": pymupdf.LINK_GOTO, "page": pno, "from": bbox, "to": point}。
执行 page.insert_link(d)。

Document 和 Page 的同类方法#

这是 Document 和 Page 级别上同类方法的概述。

Document 级别	Page 级别
Document.get_page_fonts(pno)	`Page.get_fonts()`
Document.get_page_images(pno)	`Page.get_images()`
Document.get_page_pixmap(pno, …)	`Page.get_pixmap()`
Document.get_page_text(pno, …)	`Page.get_text()`
Document.search_page_for(pno, …)	`Page.search_for()`

页码“pno”是一个 0-based 整数 -∞ < pno < page_count。

类 TableFinder#

由 Page.find_tables() 总是返回的对象。相关属性

… 属性:: tables

一个 Table 对象的列表，每个对象代表页面上找到的一个表格。如果未找到表格，则为空列表。

… 属性:: page

对 Page 对象的引用。

类 Table#

表示页面上找到的表格的对象。相关属性

bbox#: 以元组形式 (x0, y0, x1, y1) 给出的表格边界框。这是包含表格所有单元格的矩形。

cells#

类 TableHeader#

类 TableRow#

注意

大多数文档方法（左列）是出于方便而存在的，并且只是以下内容的包装器：Document[pno].<page method>。因此它们在每次执行时都加载并丢弃页面。

然而，前两个方法的工作方式不同。它们只需要页面的对象定义语句——页面本身不会被加载。因此，例如，Page.get_fonts() 是一个反向包装器，定义如下：page.get_fonts == page.parent.get_page_fonts(page.number)。

注脚

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