PyMuPDF 1.24.4 中文文档（八）（5）

PyMuPDF 1.24.4 中文文档（八）（4）https://developer.aliyun.com/article/1559659

遮蔽

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时要使用的字体，否则将被忽略。适用的规则与Page.insert_textbox()相同——这是方法Page.apply_redactions()在内部调用的方式。如果这是 CJK 或 PDF Base 14 Fonts 之一，则替换文本将垂直居中。（v1.16.12 中的新功能）注意

• 对于页面上的现有字体，请使用其引用名称作为fontname（这是其在Page.get_fonts()条目中的item[4]）。
  
• 对于一个新的、非内置字体，请按以下步骤进行：

page.insert_text(point,  # anywhere, but outside all redaction rectangles
    "something",  # some non-empty string
    fontname="newname",  # new, unused reference name
    fontfile="...",  # desired font file
    render_mode=3,  # makes the text invisible
)
page.add_redact_annot(..., fontname="newname") 

• fontsize (float) – 用于替换文本的fontsize。如果文本过大而无法容纳，将进行多次插入尝试，逐渐减小fontsize至不少于 4。如果仍然无法容纳，则根本不会进行文本插入。（v1.16.12 中的新功能）
  
• align (int) – 替换文本的水平对齐方式。参见insert_textbox()以获取可用值。如果使用 PDF 内置字体（CJK 或 PDF Base 14 Fonts），垂直对齐方式是（近似）居中的。（v1.16.12 中的新功能）
  
• fill (sequence) – 应用遮蔽后矩形的填充颜色。默认为white = (1, 1, 1)，如果指定None则也采用此颜色。要完全禁用填充颜色，请指定False。在这种情况下，矩形保持透明。（v1.16.12 中的新功能）
  
• text_color (sequence) – 替换文本的颜色。默认为black = (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_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_IF_COVERED | 1 删除完全包含在编辑注释中的图形。在删除线艺术时，请注意描边矢量图形（即类型“s”或“sf”）具有比预期更大的包装矩形：首先，必须在每个方向上至少添加路径线宽的 50%以确实包括所有的绘图内容。如果提供了所谓的“斜接限制”（请参阅 PDF 规范的第 121 页），则扩大值为 miter * width / 2。因此，当所有内容保持默认值（宽度 = 1，斜接 = 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 中更改），则删除该字符。根据字体属性和/或所选行高，可能会删除不需要的文本部分。在进行文本搜索之前，使用Tools.set_small_glyph_heights()并传递True参数可能有助于防止这种情况发生。
  
• 遮罩是替换 PDF 中单词或物理删除它们的简单方法。使用某些文本提取或搜索方法定位单词“secret”，并使用“xxxxxx”作为替换文本插入遮罩。

• 如果替换文本比原始文本更长，请小心，这可能会导致尺寸不协调、换行或根本没有新文本出现。
  
• 由于各种原因，新文本可能不会像旧文本一样完全位于同一行上 — 特别是如果替换字体不是 CJK 或者 PDF Base 14 Fonts 之一。
  

显示/隐藏历史记录 * 在 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：添加一个注释，由连接给定点的线条组成。多边形的第一个和最后一个点会自动连接，这在折线中是不会发生的。矩形会自动创建为包含这些点的最小矩形，每个点周围都有半径为 3 的圆圈（= 3 * 线宽）。以下显示了一个已经用颜色和线端修改过的“折线”。

参数：

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) 

注意

显然，文本标记注释需要知道要标记的区域的顶部、底部、左侧和右侧。如果参数是四边形，这些信息通过四边形顶点的顺序给出。相比之下，矩形提供的信息要少得多——这可以通过这样一个事实来说明，即可以用矩形的四个角构建 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)

基于它们的几何邻近性聚类矢量图形（同义词为线条艺术或图纸）。该方法遍历Page.get_drawings()的输出，并连接那些path["rect"]彼此之间距离小于某个容差值（给定在参数中）的路径。结果是一个矩形列表，每个矩形包裹着诸如带有网格线的表格、饼图、柱状图等东西。

参数：

• clip (rect_like) – 仅考虑此区域内的路径。默认为整页。
  
• drawings (list) – （可选）提供先前生成的Page.get_drawings()的输出。如果为None，则方法将执行该方法。
  
• x_tolerance (float) –
  

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)

查找页面上的表格并返回相关信息的对象。通常，许多参数的默认值将足以满足要求。调整只应在极端情况下需要。

参数：

• clip (rect_like) – 指定要在页面矩形内考虑的区域，忽略其余部分。默认为整页。
  
• strategy (str) –
  请求一个表格检测策略。有效值为“lines”、“lines_strict”和“text”。
  Default is “lines” which uses all vector graphics on the page to detect grid lines.
  Strategy “lines_strict” ignores borderless rectangle vector graphics. Sometimes single text  pieces have background colors which may lead to false columns or lines.  This strategy ignores them and can thus increase detection precision.
  If “text” is specified, text positions are used to generate “virtual” column and / or row boundaries. Use min_words_* to request the number of words for considering their coordinates.
  Use parameters vertical_strategy and horizontal_strategy instead for a more fine-grained treatment of the dimensions.
  
• horizontal_lines (sequence*[floats]*)  – y-coordinates of rows. If provided, there will be no attempt to  identify additional table rows. This influences table detection.
  
• vertical_lines (sequence*[floats]*)  – x-coordinates of columns. If provided, there will be no attempt to  identify additional table columns. This influences table detection.
  
• min_words_vertical (int) – relevant for vertical strategy option “text”: at least this many words must coincide to establish a virtual column boundary.
  
• min_words_horizontal (int) – relevant for horizontal strategy option “text”: at least this many words must coincide to establish a virtual row boundary.
  
• snap_tolerance (float) – Any two horizontal lines whose y-values differ by no more than this value will be snapped into one. Accordingly for vertical lines. Default is 3. Separate values can be specified instead for the dimensions, using snap_x_tolerance and snap_y_tolerance.
  
• join_tolerance (float) – Any two lines will be joined to one if the end and the start points differ by no more than this  value (in points). Default is 3. Instead of this value, separate values  can be specified for the dimensions using join_x_tolerance and join_y_tolerance.
  
• edge_min_length (float) – Ignore a line if its length does not exceed this value (points). Default is 3.
  
• intersection_tolerance (float)  – When combining lines into cell borders, orthogonal lines must be  within this value (points) to be considered intersecting. Default is 3.  Instead of this value, separate values can be specified for the  dimensions using intersection_x_tolerance and intersection_y_tolerance.
  
• text_tolerance (float)  – Characters will be combined into words only if their distance is no  larger than this value (points). Default is 3. Instead of this value,  separate values can be specified for the dimensions using text_x_tolerance and text_y_tolerance.
  
• add_lines (tuple*,*list) – 指定“附加”、“虚拟”矢量图的列表（即一对 point_like 对象）。这些线条可以帮助表格和/或单元格的检测，不会影响检测策略的其他方面。特别是，与 horizontal_lines 和 vertical_lines 参数相比，它们不会通过其他方式防止检测行或列。这些线条在连接、捕捉、相交、最小长度和包含性方面会像“真实”矢量图一样对待，与 clip 矩形相同。同样，不平行于任何坐标轴的线条将被忽略。
  

返回：

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

• cells: 页面上被识别为表格单元的所有边界框的列表。每个单元格都是一个 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）。支持的查看器可以将字符串呈现为表格。此输出针对小型令牌大小进行了优化，这对于 LLM/RAG feeds 特别有益。Pandas 的 DataFrame（参见下面的 to_pandas() 方法）提供了一个等效的 Markdown 表格输出，但对于人眼更易读。
  
• to_pandas(): 此方法将表格作为 pandas 的 DataFrame 返回。DataFrame 是非常多才多艺的对象，允许大量的表格操作方法，并输出到几乎 20 种广为人知的格式，其中包括 Excel 文件、CSV、JSON、Markdown 格式的表格等。DataFrame.to_markdown() 生成了一个适用于人类阅读的 Github 兼容的 Markdown 格式。然而，这种方法除了 pandas 本身外，还需要安装 tablutate) 包。
  
• header: 表头信息的 TableHeader 对象。
  
• col_count: 包含表格列数的整数。
  
• row_count: 包含表格行数的整数。
  
• rows: 包含两个属性的TableRow对象列表，bbox是行的边界框，cells是包含在此行中的表格单元格列表。
  

• TableHeader对象具有以下属性：

• bbox: 表头的边界框。
  
• cells: 包含相应列名称的边界框列表。
  
• names: 包含每个单元框文本的字符串列表。它们表示列名 - 在将表格导出到 pandas 数据框、markdown 等时使用。
  
• external: 布尔值，指示标题框是否在表格主体之外（True），或者不在外面（False）。表头从不由TableFinder逻辑识别。因此，如果external为真，则标题单元格不是由TableFinder识别的任何单元格的一部分。如果external == False，则第一行是表头。
  

请查看这些Jupyter 笔记本，涵盖了如一页上多个表格或跨多页连接表格片段等标准情况。

显示/隐藏历史记录 * 1.23.0 版本中的新功能

• 1.23.19 版本中的更改：新参数add_lines。

重要提示：

也可以使用pdf2docx 提取表格方法，如果你更喜欢。

add_stamp_annot(rect, stamp=0)

仅限 PDF：例如，向其中添加一个“橡皮图章”注释，以指示文档的预期使用（“DRAFT”、“CONFIDENTIAL”等）。

参数：

• rect（rect_like） - 注释放置的矩形。
  
• stamp（int） - 图章文本的 ID 号码。有关可用图章，请参阅图章注释图标。
  

注意：

• 图章文本及其边框将自动调整大小，并水平垂直居中于给定的矩形内。Annot.rect将自动计算以适应给定的width，通常比此参数小。
  
• 选择的字体是“Times Bold”，文本将是大写。
  
• 可以使用Annot.set_opacity()改变外观，并设置“stroke”颜色（不支持“fill”颜色）。
  
• 这可用于创建水印图像：在临时 PDF 页面上创建一个具有低不透明度值的图章注释，从中创建一个具有alpha=True的位图（可能还要旋转它），丢弃临时 PDF 页面，并使用insert_image()将该位图插入到目标 PDF 中。
  

add_widget(widget)

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

参数：

widget（Widget） - 必须预先创建的 Widget 对象。

返回：

小部件注释。

delete_annot(annot)

• 现在删除将包括任何绑定的“弹出”或响应注释及相关对象（在 v1.16.6 中更改）。

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

参数：

annot（注释） - 要删除的注释。

返回类型：

注释

返回：

删除后的注释。请记住，物理删除需要保存到一个带有垃圾 > 0 的新文件。

delete_widget(widget)

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

参数：

widget（Widget） - 要删除的小部件。

返回类型：

Widget

返回：

删除后的小部件。请记住，物理删除需要保存到一个带有垃圾 > 0 的新文件。

显示/隐藏历史记录（在 v1.18.4 中新增）

delete_link(linkdict)

仅限 PDF：从页面中删除指定的链接。参数必须是get_links()的原始项目，请参见获取链接项的描述。原因是字典的*“xref”*键，用于标识要删除的 PDF 对象。

参数：

linkdict（dict） - 要删除的链接。

insert_link(linkdict)

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

参数：

linkdict（dict） - 要插入的链接。

update_link(linkdict)

仅限 PDF：修改指定的链接。参数必须是get_links()的（修改后的）原始项目，请参见获取链接项的描述。原因是字典的*“xref”*键，用于标识要更改的 PDF 对象。

参数：

linkdict（dict） - 要修改的链接。

警告

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

get_label()

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

返回类型：

字符串

返回：

如罗马编号中的“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) – 整数序列，用于选择一个或多个小部件类型。默认为所有表单字段。例如：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, border_width=1, 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.16.18

insert_textbox(rect, buffer, fontsize=11, fontname='helv', fontfile=None, idx=0, color=None, fill=None, render_mode=0, 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.16.18

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 标签
实现 - "\n" 将被忽略，并将被视为空格。
  
• 通过这种方法可以实现以下功能：

• 像粗体、斜体、文本颜色、文本对齐、字体大小或字体切换等样式效果。
  
• 文本可以包含任意语言 - 包括从右到左的语言。
  
• 例如梵文和亚洲的其他一些语言拥有高度复杂的连字系统，两个或更多个 Unicode 字符联合形成一个字形。Story 使用软件包 HarfBuzz 处理这些情况，并产生正确的输出。
  
• 也可以通过 HTML 标签 包含图像 - Story 将处理适当的布局。这是与 Page.insert_image() 相比插入图像的另一选择。
  
• HTML 表格（标签 ）可以包含在文本中，并将得到适当处理。

• 存在链接时会自动生成链接。
  
• 如果内容不适合于矩形，则开发者有两种选择：
• either 只需收到相关通知（并接受无操作，就像其他文本框插入方法一样），
  
• 或（scale_low=0 - 默认值）缩小内容直至适合。
  

参数：

• rect（rect_like）– 页面上接收文本的矩形区域。
  
• text（str*,*Story）– 要写入的文本。可以包含纯文本和带有样式指令的 HTML 标记的混合体。或者，可以指定一个 Story 对象（在这种情况下，将省略内部 Story 生成步骤）。必须已生成具有所有必需的样式和存档信息的 Story。
  
• 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 的交叉引用或 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 s）。参见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 s）。参见 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 s）。参见 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 s 定义的连接线。参见 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 s）。参见 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 字体通过**“保留”**字体名称。还可以提供字体作为文件路径或包含字体文件映像的内存区域。

参数：

• 字体名称 (str) –
  输出文本时，此字体应被引用的名称。通常，您在这里有一个“自由”的选择（但请参阅 Adobe PDF 参考，第 16 页，第 7.3.5 节，以获取构建合法 PDF 名称的正式描述）。但是，如果它与Base14_Fonts或 CJK 字体之一匹配，fontfile和fontbuffer将被忽略。
  换句话说，您不能通过fontfile / fontbuffer插入字体，同时给出一个保留的fontname。
  注意
  可以在任何大小写混合的保留字体名称中指定，并且仍然匹配正确的内置字体定义：例如字体名称“helv”，“Helv”，“HELV”，“Helvetica”等都会导致相同的字体定义“Helvetica”。但从页面的角度来看，这些是不同的引用。在页面上使用同一字体的不同编码变体（拉丁文，希腊文，西里尔文），您可以利用这一点。
  
• fontfile (str) – 字体文件的路径。如果使用，fontname必须与所有保留名称不同。
  
• fontbuffer (bytes/bytearray) – 字体文件的内存映像。如果使用，fontname必须与所有保留名称不同。此参数通常与Font.buffer一起使用，用于支持/可用于 Font 的字体。
  
• set_simple (int) – 仅适用于fontfile / fontbuffer的情况：强制作为“简单”字体处理，即只使用字符代码直到 255。
  
• 编码 (int) – 仅适用于“Helvetica”，“Courier”和“Times”系列的Base14_Fonts。选择可用的编码之一：拉丁文（0），西里尔文（2）或希腊文（1）。对于“Symbol”和“ZapfDingBats”，仅使用默认值（0 = 拉丁文）。
  

Rytpe：

int

返回：

安装字体的xref。

注意

内置字体不会导致字体文件的包含。因此生成的 PDF 文件大小保持较小。然而，您的 PDF 查看器软件负责生成适当的外观 - 对于 CJK 字体，存在差异，无论是否如何处理。但某些情况下，Symbol 和 ZapfDingbats 处理不正确。以下是字体名称及其相应安装的基本字体名称：

Base-14 字体 [1]

字体名称	已安装基本字体	注释
helv	Helvetica	normal
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	简体中文（Serif）
china-t	Fangti	繁体中文
china-ts	Ming	繁体中文（Serif）
japan	Gothic	日文
japan-s	Mincho	日文（Serif）
korea	Dotum	韩文
korea-s	Batang	韩文（Serif）

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 中，也可以从位图、文件或内存区域中获取。

参数：

• 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 (位图) – 包含图像的位图。
  
• 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(...) 

注：

1. 该方法检测到相同图像的多次插入（如上例所示），并且仅在第一次执行时存储其数据。即使使用默认的xref=0，这也是正确的（尽管性能较差）。
   
2. 该方法无法检测在打开文件之前是否已经将相同的图像作为文件的一部分。
   
3. 您可以使用此方法为页面提供背景或前景图像，如版权或水印。请记住，如果放在前景中，水印需要一个透明的图像…
   
4. 图像可能会以未压缩的方式插入，例如如果使用了 Pixmap 或者图像具有 alpha 通道。因此，在保存文件时考虑使用deflate=True。此外，即使涉及透明度，也有控制图像大小的方法。查看如何将图像添加到 PDF 页面。
   
5. 图像以其原始质量级别存储在 PDF 中。这可能比您的显示需要的要好得多。在插入之前请考虑减小图像尺寸 - 例如通过使用 pixmap 选项然后缩小或缩放它（参见 Pixmap 章节）。也可以使用 PIL 方法Image.thumbnail()来实现这一目的。这样做可以节省很多文件大小。
   
6. 在多个页面上显示相同图像的另一种高效方法是使用另一种方法：show_pdf_page()。查看Document.convert_to_pdf()以获取可用于该方法的中间 PDF。
   

显示/隐藏历史记录 * 变更于 v1.14.1：默认情况下，图像保持其宽高比。

• 变更于 v1.14.11：添加了参数keep_proportion、rotate。
  
• 变更于 v1.14.13：
• 图片现在总是居中放置在矩形内，即图像和矩形的中心点相等。
  
• 添加了对io.BytesIO作为stream的支持。
  
• 变更于 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 处的图像。这稍有误导：实际上，使用上述 Page.replace_image() 将图像替换为一个小的透明 Pixmap。然而，可见效果是等效的。

参数：

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)

以多种格式检索页面内容。这是通过选择输出选项 opt 来调用多个 TextPage 方法的包装器：

• “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) –
  表示请求格式的字符串，其中之一为上述格式。支持大小写混合。
  值“words”和“blocks”也被接受（在 v1.16.3 中更改）。
  
• clip (rect-like) – 限制提取的文本到这个矩形。如果为 None，则取全页。对于选项“html”，“xhtml”和“xml”没有任何效果。（在 v1.17.7 中新增）
  
• flags (int) – 指示位，控制是否包含图像以及如何处理文本与空白和连字。参见 Text Extraction Flags 以获取可用指示器，以及 Text Extraction Flags Defaults 以获取默认设置。（在 v1.16.2 中新增）
  
• textpage – 使用先前创建的 TextPage。这大大减少了执行时间，降低了很多： 可达到 50%以上，甚至 95%，具体取决于提取选项。如果指定了，‘flags’和‘clip’参数将被忽略，因为它们是仅适用于 textpage 的属性。如果省略，将创建一个新的临时 textpage。（在 v1.19.0 中新增）
  
• sort (bool) – 按垂直然后水平坐标排序输出。在许多情况下，这应该足以生成“自然”的阅读顺序。对(X)HTML 和 XML 没有影响。输出选项**“words”**按单词的边界框的(y1, x0)排序。对于“blocks”，“dict”，“json”，“rawdict”，“rawjson”也是如此：它们都按相应块边界框的(y1, x0)排序。如果指定了“text”，则内部使用“blocks”。（在 v1.19.1 中新增）
  
• delimiters (str) – 使用这些字符作为额外单词分隔符与“words”输出选项（否则被忽略）。默认情况下，所有空白（包括非断行空格0xA0）表示单词的开始和结束。现在，您可以指定更多字符导致这种情况发生。例如，默认将返回"john.doe@outlook.com"作为一个单词。如果指定delimiters="@."，那么将返回四个单词"john"、"doe"、"outlook"、"com"。其他可能的用途包括忽略标点符号字符delimiters=string.punctuation。（在 v1.23.5 中新增）
  

返回类型：

str, list, dict

返回：

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

注意

1. 您可以使用此方法作为任何支持的文档类型到 TEXT、HTML、XHTML 或 XML 文档的文档转换工具。
   
2. 通过 clip 参数包含文本的决定基于字符级别：如果其边界框包含在 clip 中，则字符成为输出的一部分（在 v1.18.2 中更改）。这偏离了用于编辑注释的算法：如果其边界框与任何编辑注释相交，则字符将被移除。
   

显示/隐藏历史记录 * 在 v1.19.0 中更改：添加 文本页 参数

• 在 v1.19.1 中更改：添加 sort 参数
  
• 在 v1.19.6 中更改：为每个方法定义了新的默认标志常量。
  
• 在 v1.23.5 中更改：添加 delimiters 参数
  

get_textbox(rect, textpage=None)

检索包含在矩形中的文本。

参数：

• rect (rect-like) – 矩形。
  
• textpage – 要使用的 文本页。如果省略，则将创建一个新的临时文本页。
  

返回：

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

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

显示/隐藏历史记录 * 新增于 v1.17.7

• 在 v1.19.0 中更改：添加 文本页 参数

get_textpage(clip=None, flags=3)

创建一个用于页面的 文本页。

参数：

• flags (int) – 控制用于后续文本提取和搜索的内容的指示位 - 参见 Page.get_text() 的参数。
  
• clip (rect-like) – 限制提取的文本到此区域。（在 v1.17.7 中新增）
  

返回：

文本页

显示/隐藏历史记录 * 新增于 v1.16.5

• 在 v1.17.7 中更改：引入 clip 参数。

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

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

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

参数：

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

注意

此方法不支持裁剪参数 - OCR 将始终针对完整页面矩形进行。

返回：

TextPage 的一种执行可能比Page.get_textpage()的执行时间长得多。

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

注意

OCRed 文本仅适用于 PyMuPDF 的文本提取和搜索，如果它们的 TextPage 参数指定了此方法的输出。

这个 Jupyter 笔记本演示了使用 OCR 文本页的示例。

显示/隐藏历史记录 * v.1.19.0 中的新功能

• v1.19.1 中更改：支持对页面进行完整和部分 OCR。

get_drawings(extended=False)

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

返回：

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

用于填充、描边和填充-描边路径的路径字典已经设计成与形状类兼容。以下是关键字：

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

键"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 的直线（点对象）。
  
• ("c", p1, p2, p3, p4) - 从 p1 到 p4 的三次贝塞尔曲线（p2 和 p3 是控制点）。所有对象均为点类型。
  
• ("re", rect, orientation) - 一个矩形。同一路径中的多个矩形现在被检测到（v1.18.17 中更改）。整数orientation是 1 或-1，表示所包含区域是否向左旋转（1 = 逆时针），或向右旋转[7]（v1.19.2 中更改）。
  
• ("qu", quad) - 一个四边形。检测到 3 或 4 条连续的线实际上表示一个四边形（v1.19.2 中更改）。
  

使用类 Shape，您应该能够在正常情况下，在独立的（PDF）页面上高度还原原始图纸，而不是过于复杂的情况下。请参阅关于限制的以下注释。有关“提取图纸”的编码草案可在第 FAQ 章节中找到。

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

任何级别小于其前任的路径都将结束（至少）前面层次结构的范围。与前一个剪辑级别相同的“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 行的剪辑适用于包括第 7 行在内的路径。第 2 行的组适用于第 3 到第 5 行，第 3 行的剪辑仅适用于第 4 行。

第 4 行中的“stroke”受第 2 行的“group”和第 3 行的“clip”（它又是第 0 行剪辑的子集）控制。

• “clip” 字典。其值（尤其是“scissor”）在后续字典具有**更大“level”**值时仍然有效/适用。

键	值
closePath	与“stroke”或“fill”字典中相同
even_odd	与“stroke”或“fill”字典中相同
items	与“stroke”或“fill”字典中相同
rect	与“stroke”或“fill”字典中相同
layer	与“stroke”或“fill”字典中相同
level	与“stroke”或“fill”字典中相同
scissor	剪辑矩形
type	“clip”
• 
  
• “group” 字典。其值仅在后续字典具有**较大“level”**值时有效。任何具有相等或更低级别的字典将结束此组。

键	值
rect	与“stroke”或“fill”字典中相同
layer	与“stroke”或“fill”字典中相同
level	与“stroke”或“fill”字典中相同
isolated	（布尔值）此组是否被隔离
knockout	（布尔值）是否为“Knockout Group”
blendmode	BlendMode 的名称，默认为“Normal”
opacity	浮点数值，范围在 [0, 1] 内。
type	“group”
• 
  

注意

该方法基于 Page.get_cdrawings() 的输出 - 这种方法速度更快，但处理其输出需要更多注意。

显示/隐藏历史记录 * 新增于 v1.18.0

• Changed in v1.18.17
  
• Changed in v1.19.0: 添加了“seqno”键，删除了“clippings”键
  
• Changed in v1.19.1: “color” / “fill” 键现在总是 RGB 元组或 None。这解决了由于奇异的颜色空间而引起的问题。
  
• Changed in v1.19.2: 添加了关于“re”项覆盖区域*“方向”*的指示符。
  
• Changed in v1.22.0: 添加新键 "layer"，其中包含路径的可选内容组的名称（或 None）。
  
• Changed in 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

• Changed in v1.19.0: 移除了“clippings”键，添加了“seqno”键。
  
• Changed in v1.19.1: 总是生成 RGB 颜色元组。
  
• Changed in 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)

返回一个包含所有显示在页面上的图像的元信息字典列表。这适用于所有文档类型。从技术上讲，这是 Page.get_text() 的字典输出的子集：图像的二进制内容和页面上的任何文本都被忽略。

参数：

• hashes (bool) – 为每个遇到的图像计算 MD5 哈希码，以便识别图像的重复项。这将在输出中添加键 "digest"，其值为一个 16 字节的 bytes 对象。（在 v1.18.13 中新增）
  
• xrefs (bool) – 仅适用于 PDF。 尝试查找每个图像的 xref。意味着 hashes=True。向字典添加 "xref" 键。如果未找到，则值为 0，这意味着图像可能是“内联”或其他无法检测到的类型。请注意，此选项响应时间较长，因为将至少两次计算每个具有 xref 的图像的 MD5 哈希码。（在 v1.18.13 中新增）
  

返回类型：

list[dict]

返回：

一个包含所有显示在页面上的图像的字典列表。这与包含在 Page.get_text() 中的图像块不同，后者不会加载图像的二进制内容，从而显著减少了内存使用量。字典的布局类似于 page.get_text("dict") 中的图像块。

Key	Value
number	块编号 (int)
bbox	页面上的图像边界框，rect_like
width	原始图像宽度 (int)
height	原始图像高度 (int)
cs-name	颜色空间名称 (str)
colorspace	颜色空间中的颜色数 (int)
xres	x 方向分辨率 (int)
yres	y 方向分辨率 (int)
bpc	每组分量的比特数 (int)
size	图像占用的存储空间 (int)
digest	MD5 哈希码 (bytes)，如果 hashes 为 true
xref	图像的 xref 或者如果 xrefs 为 true 则为 0
transform	将图像矩形变换为 bbox 的矩阵，matrix_like

相同图像的多次出现始终会被报告。您可以通过比较它们的digest值来检测重复项。

显示/隐藏历史记录 * 在 v1.18.11 中新增

• 在 v1.18.13 中更改：添加了图像 MD5 哈希码计算和 xref 搜索。

get_xobjects()

仅适用于 PDF：返回页面引用的表单 XObject 的列表。是Document.get_page_xobjects()的包装器。

get_image_rects(item, transform=False)

仅适用于 PDF：返回嵌入图像的边界框和变换矩阵。这是Page.get_image_bbox()的改进版本，具有以下区别：

• 如何调用图像没有限制（由页面或其一个表单 XObject 调用）。结果始终完整且正确。
  
• 结果是 Rect 或(Rect, Matrix)对象的列表 – 取决于transform。每个列表项表示页面上图像的一个位置。Page.get_image_bbox()可能无法检测到多个出现。
  
• 该方法调用Page.get_image_info()，因此其响应时间比Page.get_image_bbox()明显更长，因为xrefs=True。
  

参数：

• item (list*,str,int) – 列表Page.get_images()中的一个项目，或者是这样一个项目的参考name*条目（item[7]），或者是图像xref。
  
• transform (bool) – 同时返回用于将图像矩形变换为页面上的边界框的矩阵。如果为真，则返回元组(bbox, matrix)。
  

返回类型：

列表

返回：

对页面上每个图像出现的边界框及其相应的变换矩阵。如果项目不在页面上，则返回空列表[]。

显示/隐藏历史记录 新增于 v1.18.13

get_image_bbox(item, transform=False)

仅适用于 PDF：返回嵌入图像的边界框和变换矩阵。

参数：

• item (list*,str) – 列表Page.get_images()中的一个项目，如果指定了full=True，或者是这样一个项目的参考name*条目，即 item[-3]（或分别为 item[7]）。
  
• transform (bool) – 返回用于将图像矩形变换为页面上的边界框的矩阵（自 v1.18.11 新增）。默认值仅为边界框。如果为真，则返回元组(bbox, matrix)。
  

返回类型：

Rect 或(Rect, Matrix)

返回：

图像的边界框 – 可选地也包括其变换矩阵。

显示/隐藏历史记录 （自 v1.16.7 更改）：如果页面实际上未显示此图像，则现在返回一个无限矩形。在以前的版本中，会引发异常。形式上无效的参数仍会引发异常。

• （自 v1.17.0 更改）：仅考虑页面直接引用的图像。这意味着忽略了嵌入的 PDF 页面中的图像，并引发异常。
  
• （自 v1.18.5 变更）：删除 v1.17.0 中引入的限制：页面图像列表的任何项目都可以指定。
  
• （自 v1.18.11 变更）：部分重新引入限制：只考虑页面直接引用或页面直接引用的表单 XObject 的图像。
  
• （自 v1.18.11 变更）：还可以选择将转换矩阵与 bbox 一起返回，作为元组(bbox, transform)。
  

注意

1. 请注意，Page.get_images() 可能包含“无效”条目，即页面不显示的图像。这不是错误，而是 PDF 创建者的意图。在这种情况下，不会引发异常，但会返回一个无限大的矩形。您可以通过在调用此方法之前执行Page.clean_contents()来避免这种情况发生。
   
2. 图像的“转换矩阵”被定义为矩阵，其中表达式bbox / transform == pymupdf.Rect(0, 0, 1, 1)为真，详细信息请查看：图像转换矩阵。
   

显示/隐藏历史记录 * 自 v1.18.11 变更：返回图像转换矩阵

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

从页面创建一个 SVG 图像。目前仅支持全页图像。

参数：

• 矩阵（类似矩阵） - 一个矩阵，默认为单位矩阵。
  
• text_as_path（布尔值） - 控制文本的表示方式。True 将每个字符输出为一系列基本绘制命令，这导致浏览器中文本显示更精确，但对于面向文本的页面来说，输出量非常大。对于缺失字体，Internet 浏览器将回退到一些默认值 - 导致外观不佳。如果要解析 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)

从页面创建一个位图。这可能是创建位图最常用的方法之一。

所有参数均为仅限关键字。

参数：

• 矩阵（类似矩阵） - 默认为单位矩阵。
  
• dpi（整数） - x 和 y 方向上的期望分辨率。如果不为None，则忽略"matrix"参数。（v1.19.2 中新增）
  
• colorspace（字符串或颜色空间） - 所需的颜色空间之一：“GRAY”、“RGB”或“CMYK”（大小写不敏感）。或指定一个颜色空间，例如预定义的之一：csGRAY、csRGB或csCMYK。
  
• clip (irect_like) – 限制渲染到此区域与页面矩形的交集。
  
• alpha (bool) –是否添加 alpha 通道。如果你不真正需要透明度，请始终接受默认值False。这将节省大量内存（RGB 的情况下约 25%……像素图通常很大！），同时也节省处理时间。还要注意图片渲染的一个重要差异：使用True时，像素图的样本区域将被预先清除为0x00，这导致页面空白处为透明。使用False时，像素图的样本将被预先清除为0xff，这导致页面空白处为白色。 显示/隐藏历史记录 在 v1.14.17 版中更改 默认 alpha 值现在为False。
• 生成时使用alpha=True
• 
  
• 生成时使用alpha=False
• 
  
• annots (bool) – (自 1.16.0 版起新增) 是否也渲染注释或抑制它们。你可以单独为注释创建像素图。
  

返回类型：

Pixmap

返回：

页面的像素图。对于精确控制生成图像，迄今为止最重要的参数是matrix。例如，你可以通过使用**Matrix(xzoom,  yzoom)**来增加或减少图像分辨率。如果 zoom > 1，你将获得更高的分辨率：zoom=2  将在该方向上增加两倍的像素数，从而生成一个 2  倍大的图像。非正值将水平翻转或垂直翻转。类似地，矩阵还允许你旋转或剪切，并且你可以通过矩阵乘法组合效果。查看 Matrix  部分以了解更多信息。请注意

• 如果 alpha=True，像素图将具有*“预乘”*像素。要了解一些背景，例如查找“预乘 alpha”这里。
  
• 该方法将尊重任何页面旋转，并不会超出clip与Page.cropbox的交集。如果需要页面的媒体框（如果这是一个不同的矩形），可以使用以下代码段来实现：

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]: 

显示/隐藏历史记录 * 在 v1.19.2 版中更改：添加了对参数 dpi 的支持。

annot_names()

只返回 PDF：列出注释、小部件和链接的名称列表。从技术上讲，这些是页面 /Annots 数组中每个 PDF 对象的 /NM 值。

返回类型：

列表

显示/隐藏历史记录 * 新增于 v1.16.10

annot_xrefs()

只返回 PDF：返回注释、小部件和链接的 :dataxref 数字列表 – 从技术上讲是在页面的 /Annots 数组中找到的所有条目。

返回类型：

列表

返回：

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

显示/隐藏历史记录 * 自 v1.17.1 新增

load_annot(ident)

仅适用于 PDF：返回由ident标识的注释。这可以是其唯一名称（PDF /NM键）或其xref。

参数：

ident（str，int）– 注释名称或 xref。

返回类型：

注释

返回：

注释或None。

注意

方法Page.annot_names()、Page.annot_xrefs()提供名称或 xrefs 列表，从中可以选择项目并通过此方法加载。

显示/隐藏历史记录 * 自 v1.17.1 新增

load_widget(xref)

仅适用于 PDF：返回由xref标识的字段。

参数：

xref（int）– 字段的 xref。

返回类型：

小部件

返回：

字段或None。

注意

这类似于类似方法Page.load_annot()，只是这里仅支持 xref 作为标识符。

显示/隐藏历史记录 * 自 v1.19.6 新增

load_links()

返回页面上的第一个链接。与属性first_link同义。

返回类型：

链接

返回：

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

set_rotation(rotate)

仅适用于 PDF：设置页面的旋转。

参数：

rotate（int）– 指定所需旋转角度的整数。必须是 90 的整数倍。值将转换为 0、90、180、270 中的一个。

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 给出的可见区域内。

示例：显示相同源页面，分别旋转 90 度和-90 度：

>>> 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") 

显示/隐藏历史记录 * 从 v1.14.11 版本开始更改：参数 reuse_xref 已被弃用。现在支持将源矩形居中放置在目标矩形中，任何旋转角度均支持。

• 从 v1.18.3 版本开始更改：新参数 oc。

new_shape()

仅限于 PDF：为页面创建一个新的 Shape 对象。

返回类型：

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”，则会找到。 对于德语的 umlauts 等情况也是如此。
  
• 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”连字符化在换行处，则会找到它，并返回两个矩形：一个围绕“meth”（没有连字符），另一个围绕“od”。
  

注意

该方法支持多行文本标记注释：您可以将完整的返回列表用作一个单一的参数来创建注释。

注意

• 有一个棘手的方面：搜索逻辑将needle的连续多次出现视为一个：假设needle是“abc”，页面包含“abc”和“abcabc”，那么只会返回两个矩形，一个用于“abc”，另一个用于“abcabc”。
  
• 你可以随时使用Page.get_textbox()来检查每个矩形周围实际包围的文本。
  

注意

支持正则表达式的一个棘手的方面是指定"needle"字符串时将无法实现：如果您需要沿着这个方向进行操作，请首先提取所需格式的文本，然后通过与一些正则表达式模式匹配来选择结果。 以下是匹配单词的示例：

>>> 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])] 

matches列表将包含与给定模式匹配的单词。 以同样的方式，您可以从page.get_text("dict")的输出中选择span["text"]。

显示/隐藏历史记录 * 在 v1.18.2 中更改：添加`clip`参数。 删除`hit_max`参数。 添加默认的“去连字化”。

• 在 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：更改页面的可见部分。

参数：

r（rect_like）– 页面的新可见区域。注意，这必须在未旋转的坐标中指定，不能为空，也不能无限大，并且完全包含在Page.mediabox中。

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

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

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。”

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

类型：

int

cropbox_position

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

类型：

Point

cropbox

PDF 的页面/CropBox。始终返回未旋转的页面矩形。对于非 PDF，这将始终等于页面矩形。

注意

在 PDF 中，/MediaBox、/CropBox 和页面矩形之间的关系有时可能会令人困惑，请查阅MediaBox词汇表。

类型：

Rect

artbox

bleedbox

trimbox

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

类型：

Rect

mediabox_size

包含页面的Page.mediabox的宽度和高度，否则为Page.rect的右下坐标。

类型：

Point

mediabox

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

类型：

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 矩形。

类型：

矩阵

rotation_matrix

derotation_matrix

这些矩阵可以用于处理旋转的 PDF 页面。在向 PDF 页面添加/插入任何内容时，始终使用未旋转页面的坐标。这些矩阵有助于在两种状态之间进行转换。例如：如果页面旋转了 90 度，A4 页面左上角点(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)
>>> 

类型：

矩阵

first_link

包含页面的第一个链接（或无）。

类型：

链接

first_annot

包含页面的第一个注释（或无）。

类型：

注释

first_widget

包含页面的第一个部件（或无）。

类型：

部件

number

页面号码。

类型：

整数

parent

拥有的文档对象。

类型：

文档

rect

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

类型：

矩形

xref

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

类型：

矩形

get_links() 条目描述

Page.get_links()列表的每个条目都是一个带有以下键的字典：

• kind：（必需）指示链接种类的整数。这是LINK_NONE、LINK_GOTO、LINK_GOTOR、LINK_LAUNCH或LINK_URI中的一个。有关这些名称的值和含义，请参阅链接目标种类。
  
• from：（必需）描述页面可见表示上的“热点”位置的矩形（光标更改为手形图像的位置，通常为）。
  
• page：表示目标页面的基于 0 的整数。对于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*。对于get_links()列表中的所有条目，如果 MuPDF 不支持其中任何链接，则为-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目标的有效性，因此这些目标始终会被接受。

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

1. 确定当前页面上链接应放置的矩形。这可以是图像或某些文本的 bbox。
   
2. 确定目标页面号（“pno”，从 0 开始）及其上的 Point，链接应指向该处。
   
3. 创建字典d = {"kind": pymupdf.LINK_GOTO, "page": pno, "from": bbox, "to": point}。
   
4. 执行page.insert_link(d)。
   

阅读（涉及方法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目标通常无法检查其有效性，因此总是被接受。

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

1. 确定当前页面上链接应放置的矩形。这可以是图像的 bbox 或某些文本。
   
2. 确定目标页面号码（基于 0）和 Point 位置，链接应指向该位置。
   
3. 创建字典d = {"kind": pymupdf.LINK_GOTO, "page": pno, "from": bbox, "to": point}。
   
4. 执行page.insert_link(d)。
   

文档 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 的整数-∞ < pno < page_count。

注意

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

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

脚注

对此页面有任何反馈吗？

---

本软件按原样提供，不附带任何明示或暗示的担保。本软件按许可分发，未经明确授权不得复制、修改或分发。请参阅artifex.com获取许可信息，或联系美国旧金山 CA 94129 Mesa 街 39 号 108A 号 Artifex Software Inc.了解更多信息。

本文档覆盖了所有版本直至 1.24.4。