PyMuPDF 1.24.4 中文文档（七）（2）

PyMuPDF 1.24.4 中文文档（七）（1）https://developer.aliyun.com/article/1559543

参数：

xref (int) – 图像或表单 X 对象的xref号。有效的交叉引用号由Document.get_page_images()或Document.get_page_xobjects()返回。对于无效的号码，会引发异常。

返回类型：

int

返回：

可选内容对象的交叉引用号，如果没有则为零。

set_oc(xref, ocxref)

• v1.18.4 版新功能

如果xref代表图像或表单 X 对象，则设置或删除可选内容对象的交叉引用号ocxref。

参数：

• xref (int) – 图像或表单 X 对象的xref [5]。有效的交叉引用号由Document.get_page_images()或Document.get_page_xobjects()返回。对于无效的号码，会引发异常。
  
• ocxref (int) – OCG / OCMD的xref号。如果不为零，则无效引用会引发异常。如果为零，则删除任何 OC 引用。
  

get_layers()

• v1.18.3 版新功能

显示可选层配置。总是有一个标准配置，不包含在响应中。

>>> for item in doc.get_layers(): print(item)
{'number': 0, 'name': 'my-config', 'creator': ''}
>>> # use 'number' as config identifier in add_ocg 

add_layer(name, creator=None, on=None)

• v1.18.3 版新功能

添加一个可选内容配置。层用作可选内容组的 ON / OFF 状态集合，并允许在同一文档上快速切换不同视图的可见性。

参数：

• name (str) – 任意名称。
  
• creator (str) – （可选）创建软件。
  
• on (sequ) – 应在激活此层时设置为 ON 的 OCG xref号序列。未列出的所有 OCG 将被设置为 OFF。
  

switch_layer(number, as_default=False)

• v1.18.3 版新功能

切换到由可选层配置号定义的文档视图。这是临时的，除非设为默认。

参数：

• number (int) – 由Document.layer_configs()返回的配置号。
  
• as_default (bool) – 将此配置设置为默认配置。
  

激活在识别的层中定义的 OCG 的 ON / OFF 状态。如果as_default=True，则还会合并所有层，包括标准层，并将结果写回标准层，并删除所有可选层。

add_ocg(name, config=-1, on=True, intent='View', usage='Artwork')

• v1.18.3 版新功能

添加一个可选内容组。OCG 是确定对象可见性的最重要信息单元。对于 PDF 文档，至少必须存在一个 OCG 才能被视为具有可选内容。

参数：

• name (str) – 任意名称。将在支持 PDF 查看器中显示。
  
• config (int) – 层配置号。默认为-1 是标准配置。
  
• on (bool) – 指向此 OCG 的对象的标准可见性状态。
  
• intent (str*,*list) – 声明可见性意图的字符串或字符串列表。可以选择两个 PDF 标准值：“View”和“Design”。默认为“View”。拼写非常重要。
  
• usage (str) – OCG 可见性的另一个影响因素。这将成为 OCG 的/Usage键的一部分。可以选择两个 PDF 标准值：“Artwork”和“Technical”。默认为“Artwork”。请仅在必要时更改。
  

返回：

创建的 OCG 的xref。用作支持对象中oc参数的条目。

注意

可能会创建具有相同参数的多个 OCG。这不会引起问题。Document.save()的垃圾选项 3 将清除任何重复项。

set_ocmd(xref=0, ocgs=None, policy='AnyOn', ve=None)

• v1.18.4 中的新功能

创建或更新一个OCMD，Optional Content Membership Dictionary（可选内容成员字典）。

参数：

• xref (int) – 要更新的 OCMD 的xref，或者为新的 OCMD 为 0。
  
• ocgs (list) – 一系列现有xref PDF 对象的编号。
  
• policy (str) – “AnyOn”（默认），“AnyOff”，“AllOn”，“AllOff”（混合或小写）之一。
  
• ve (list) – “可见性表达式”。这是一个任意嵌套其他列表的列表 – 详见下面的解释。如果需要制定更复杂的条件，可用作ocgs / policy的替代。
  

返回类型：

int

返回：

创建 OCMD 的xref。用作支持对象中oc=xref参数，以及分别在Document.set_oc()或Annot.set_oc()中使用。

注意

类似于 OCG，OCMD 具有开启或关闭的可见性状态，并且可以像 OCG 一样使用。与 OCG 不同的是，通过评估一个或多个 OCG 的状态来确定 OCMD 的状态，通过特殊形式的布尔表达式。如果表达式评估为 true，则 OCMD 状态为 ON，false 为 OFF。

有两种方式可以制定 OCMD 的可见性：

1. 使用ocgs和policy的组合：policy的值解释如下：

• AnyOn – （默认）如果至少有一个 OCG 打开，则为 true。
• 
  
• AnyOff – 如果至少有一个 OCG 关闭，则为 true。
• 
  
• AllOn – 如果所有 OCG 都打开，则为 true。
• 
  
• AllOff – 如果所有 OCG 都关闭，则为 true。
• 
  

假设您希望两个 PDF 对象一次只显示一个（如果一个打开，则另一个必须关闭）：

解决方案：使用一个OCG作为对象 1 的对象，使用一个OCMD作为对象 2 的对象。通过set_ocmd(ocgs=[xref], policy="AllOff")创建 OCMD，其中xref为 OCG 的编号。

1. 使用可见性表达式 ve：这是一个包含两个或更多项的列表。第一个项是一个逻辑关键词：字符串**“and”、“or”或“not”**之一。第二个及其后的项必须是整数或另一个列表。整数必须是xref的编号。列表必须再次至少有两个以布尔关键词开头的项。这种语法有些笨拙，但非常强大：

• 每个列表必须以逻辑关键词开头。
• 
  
• 如果关键词是**“not”，那么列表必须正好有两个项。如果是“and”或“or”**，则可以跟随任意数量的其他项。
• 
  
• 逻辑关键词后面的项目可以是整数或者再次是一个列表。整数必须是 OCG 的 xref。列表必须符合前述规则。
• 
  

示例：

• set_ocmd(ve=["or", 4, ["not", 5], ["and", 6, 7]])。如果以下条件为真，则返回 ON：“4 为 ON，或者 5 为 OFF，或者 6 和 7 同时为 ON”。
• 
  
• set_ocmd(ve=["not", xref])。这与第 1 创建的 OCMD 示例具有相同的效果。
• 
  

更多详细信息和示例请参见 Adobe PDF References 第 224 页。还请查看示例脚本这里。

可见性表达式/VE是 PDF 规范 1.6 版的一部分。因此，并非所有 PDF 查看器/阅读器可能已支持此功能，因此对于这些情况会以某种标准方式进行响应。

get_ocmd(xref)

• 自 v1.18.4 起新增功能

检索OCMD的定义。

参数：

xref (int) – OCMD 的xref。

返回类型：

字典

返回：

带有键xref、ocgs、policy和ve的字典。

get_layer(config=-1)

• 自 v1.18.3 起新增功能

特定配置中可选内容组的状态列表。这是一个包含数组/ON、/OFF或某些单选按钮组(/RBGroups)中的 OCG 交叉引用号列表的字典。

参数：

config (int) – 配置层（默认为标准配置层）。

>>> pprint(doc.get_layer())
{'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]}
>>> 

set_layer(config, *, on=None, off=None, basestate=None, rbgroups=None, locked=None)

• 自 v1.18.3 起新增功能
  
• 自 v1.22.5 起更改：支持锁定OCG 的列表。
  

大量可选内容组的状态更改。永久设置 OCG 的状态。

参数：

• config (int) – 所需的配置层，选择-1 表示默认配置层。
  
• on (list) – 设置为 ON 的 OCG 的xref列表。替换以前的值。如果使用basestate="ON"，应指定为空列表将不再设置任何 OCG 为 ON。
  
• off (list) – 设置为 OFF 的 OCG 的xref列表。替换以前的值。如果使用basestate="OFF"，应指定为空列表将不再设置任何 OCG 为 OFF。
  
• basestate (str) – 未在on或off中提到的 OCG 的状态。可能的值为“ON”、“OFF”或“Unchanged”。大小写皆可。
  
• rbgroups (list) – 一个列表的列表。替换以前的值。每个子列表应包含两个或更多个 OCG xrefs。同一子列表中的 OCG 就像单选按钮组中的按钮：设置一个为 ON 将自动将所有其他组成员设置为 OFF。
  
• locked (list) – 无法通过用户界面更改的 OCG xref 号列表。
  

值 None 将不更改相应的 PDF 数组。

>>> doc.set_layer(-1, basestate="OFF")  # only changes the base state
>>> pprint(doc.get_layer())
{'basestate': 'OFF', 'off': [8, 9, 10], 'on': [5, 6, 7], 'rbgroups': [[7, 10]]} 

get_ocgs()

• v1.18.3 中的新功能

所有可选内容组的详细信息。这是一个字典，形如（键是 OCG 的 xref）：

>>> pprint(doc.get_ocgs())
{13: {'on': True,
 'intent': ['View', 'Design'],
 'name': 'Circle',
 'usage': 'Artwork'},
14: {'on': True,
 'intent': ['View', 'Design'],
 'name': 'Square',
 'usage': 'Artwork'},
15: {'on': False, 'intent': ['View'], 'name': 'Square', 'usage': 'Artwork'}}
>>> 

layer_ui_configs()

• v1.18.3 中的新功能

显示可由支持 PDF 查看器的用户界面修改的可选内容的可见性状态。

• 仅报告当前选择的层配置中包含的项目。
• 
  
• 字典键的含义如下：

• depth: 在 /Order 数组中的项目嵌套级别
• 
  
• locked: 如果无法通过用户界面更改，则为 true
• 
  
• number: 运行的顺序号
• 
  
• on: 项目状态
• 
  
• text: 源 OCG 的文本字符串或名称字段
• 
  
• type: “label”（由文本字符串设置），“checkbox”（由单个 OCG 设置）或 “radiobox”（由一组连接的 OCG 设置之一）

set_layer_ui_config(number, action=0)

• v1.18.3 中的新功能

修改内容组的 OC 可见性状态。这类似于支持 PDF 查看器提供的功能。

请注意，可见性不是与 OCG 存储的属性。它甚至可能根本不在 PDF 文档中存在。相反，当前的可见性是使用某些支持 PDF 消费软件的用户界面临时设置的。此方法提供了相同类型的功能。

要进行永久更改，请使用 Document.set_layer()。

参数：

• number (int*,*str) – 列表 Document.layer_configs() 中项目的顺序号或其中一个项目的“text”。
  
• action (int) – PDF_OC_ON = 设置为开启（默认），PDF_OC_TOGGLE = 切换开/关，PDF_OC_OFF = 设置为关闭。
  

authenticate(password)

使用字符串 password 解密文档。如果成功，可以访问文档数据。对于 PDF 文档，“所有者”和“用户”具有不同的特权，因此可能存在这些授权级别的不同密码。该方法将自动为提供的密码建立适当的（所有者或用户）访问权限。

参数：

password (str) – 所有者或用户密码。

返回类型：

int

返回：

如果成功，则返回正值，否则返回零（字符串不匹配任何密码）。如果返回正值，则指示器 Document.is_encrypted 将设置为 False。正返回代码携带以下详细信息：

• 1 => 已验证，但 PDF 既没有所有者密码也没有用户密码。
  
• 2 => 使用 用户 密码进行身份验证。
  
• 4 => 使用 所有者 密码进行身份验证。
  
• 6 => 已验证，且两个密码相等 – 可能是一种罕见的情况。
  

注意

文档可能由所有者保护，但不是由用户密码保护。通过 doc.authenticate("") == 2 可检测此情况。这允许无需验证即可打开和阅读文档，但依赖于Document.permissions值，其他操作可能会受限制。在这种情况下，PyMuPDF（如 MuPDF）忽略这些限制。因此，与任何 PDF 查看器相反，例如即使相应的权限标志PDF_PERM_COPY、PDF_PERM_MODIFY、PDF_PERM_ANNOTATE等被关闭，您也可以提取文本并添加或修改内容！在适用的情况下，您有责任构建合法合规的应用程序。

get_page_numbers(label, only_one=False)

• 新功能在 v 1.18.6 中引入

仅限 PDF：返回具有指定标签的页面号列表 – 请注意，PDF 中的标签可能不唯一。这意味着需要对所有页面号进行顺序搜索以比较它们的标签。

注意

实施细节 – 用于此目的，页面不会被加载。

参数：

• 标签 (str) – 要查找的标签，例如“vii”（罗马数字 7）。
  
• only_one (bool) – 在第一次命中后停止。如果标签是唯一的已知值或者页面很多等情况下非常有用。默认会检查每个页面号。
  

返回类型：

列表

返回：

具有此标签的页面号列表。如果找不到、未定义标签等，则为空。

get_page_labels()

• 新功能在 v1.18.7 中引入

仅限 PDF：提取页面标签定义列表。通常用于在输入Document.set_page_labels()之前进行修改。

返回：

一个字典列表，如Document.set_page_labels()中所定义。

set_page_labels(labels)

• 新功能在 v1.18.6 中引入

仅限 PDF：添加或更新 PDF 的页面标签定义。

参数：

标签 (列表) –

一个字典列表。每个字典定义一个标签构建规则和基于 0 的“起始”页码。该起始页是首个适用于该标签定义的页面。每个字典最多有 4 个条目，类似于 {'startpage': int, 'prefix': str, 'style': str, 'firstpagenum': int}，具有以下条目。

• startpage: (int) 应用标签规则的第一页号（基于 0）。此键必须存在。规则适用于文档的所有后续页面，直到超过下一个较大页码的规则为止。
  
• prefix: (str) 一个任意字符串，用于开始标签，例如“A-”。默认为“”。
  
• style: (str) 编号样式。可选的有“D”（十进制）、“r”/“R”（罗马数字，小写 / 大写）、“a”/“A”（字母编号，小写 / 大写：“a”到“z”，然后“aa”到“zz”等）。默认为“”。如果为空，则范围内的页面将获得相同的由 prefix 值组成的标签。如果 prefix 也省略，则标签将是“”。
  
• firstpagenum: (int) 从该值开始编号。默认为 1，较小的值将被忽略。
  

例如：

[{'startpage': 6, 'prefix': 'A-', 'style': 'D', 'firstpagenum': 10},
 {'startpage': 10, 'prefix': '', 'style': 'D', 'firstpagenum': 1}] 

将为页面 6、7 等生成标签“A-10”、“A-11”、“A-12”、“A-13”、“1”、“2”、“3”等，直到文档末尾。页面 0 到 5 将标签为“”。

make_bookmark(loc)

• 新功能 v.1.17.3

返回可重新流动文档中的页面指针。在重新布局文档后，此方法的结果可用于查找页面的新位置。

注意

不要与目录项 TOC 混淆。

参数：

loc（列表*,*元组） – 页面位置。必须是有效的 (章节, 页数)。

返回类型：

指针

返回：

以指针格式的长整数。用于找到文档重新布局后页面的新位置。不要触摸或重新分配。

find_bookmark(bookmark)

• 新功能 v.1.17.3

在重新布局文档后返回新的页面位置。

参数：

bookmark（指针） – 由 Document.make_bookmark() 创建。

返回类型：

元组

返回：

页面的新位置（章节, 页数）。

chapter_page_count(chapter)

• 新功能 v.1.17.0

返回章节的页数。

参数：

chapter（整数） – 基于 0 的章节编号。

返回类型：

整数

返回：

章节中的页数。仅适用于支持章节的文档类型（目前为 EPUB）。

next_location(page_id)

• 新功能 v.1.17.0

返回下一页的位置。

参数：

page_id（元组） – 当前页面 id。这必须是标识现有页面的元组 (章节, 页数)。

返回：

下一页的元组，即 (章节, 页数 + 1) 或 (章节 + 1, 0)，或 如果参数是最后一页，则为空元组 ()。仅适用于支持章节的文档类型（目前为 EPUB）。

prev_location(page_id)

• 新功能 v.1.17.0

返回前一页的定位器。

参数：

page_id（元组） – 当前页面 id。这必须是标识现有页面的元组 (章节, 页数)。

返回：

前一页的元组，即 (章节, 页数 - 1) 或前一章节的最后一页，或 如果参数是第一页，则为空元组 ()。仅适用于支持章节的文档类型（目前为 EPUB）。

load_page(page_id=0)

• 在 v1.17.0 中更改：对于支持所谓的“章节结构”（如 EPUB）的文档类型，页面也可以通过章节编号和相对页数的组合加载，而不是绝对页数。这应该 显著加快 对大型文档的访问速度。

为进一步处理（如渲染、文本搜索等）创建一个 Page 对象。

参数：

page_id（整数*,*元组） –

(v1.17.0 中更改)

可以是基于 0 的页码，或元组 (章节, 页数)。对于 整数，任何 -∞ < page_id < page_count 都可以接受。当 page_id 为负数时，将会添加 page_count。例如：要加载最后一页，你可以使用 doc.load_page(-1)。之后，你将拥有 page.number = doc.page_count - 1。

对于元组，chapter 必须在 Document.chapter_count 范围内，并且 pno 必须在该章节的 Document.chapter_page_count() 范围内。这两个值都是从 0 开始计数的。使用这种表示法，Page.number 将等于给定的元组。仅适用于支持章节结构的文档类型（目前仅限 EPUB）。

返回类型：

Page

注意

文档还遵循带有页码索引的 Python 序列协议：doc.load_page(n) == doc[n]。

仅限绝对页码，如*“for page in doc: …”* 和 “for page in reversed(doc): …” 将按顺序产生文档的页面。请参考 Document.pages()，允许像切片一样处理页面。

您还可以使用基于章节的新页面标识的索引表示法：使用 page = doc[(5, 2)] 加载第六章的第三页。

为了保持一致的 API，在不支持章节结构（如 PDF）的文档类型中，Document.chapter_count 为 1，也可以通过元组*(0, pno)*加载页面。参见 [3] 注释以获取性能改进的评论。

reload_page(page)

• v1.16.10 版中的新功能

仅适用于 PDF：在完成并更新所有待定更改后，提供页面的新副本。

参数：

page (Page) – 页面对象。

返回类型：

Page

返回：

相同页面的新副本。将会完成所有待定更新（如注释或小部件），并加载页面的新副本。

注意

在典型用例中，在添加或更改注释/小部件后应获取页面 Pixmap。为了强制所有这些更改在页面结构中反映出来，该方法将重新加载一个新副本，同时保持对象层次结构“文档 -> 页面 -> 注释/小部件”不变。

resolve_names()

仅适用于 PDF：将目标名称转换为 Python 字典。

返回：

具有以下布局的字典：

• key: (str) 名称。
  
• value: (dict) 具有以下布局：

• ”page”: 目标页码（从 0 开始）。如果找不到页码，则返回-1。
  
• ”to”: (x, y) 页面上的目标点。目前在 PDF 坐标中，即点(0,0)是页面的左下角。
  
• ”zoom”: (float) 缩放因子。
  
• ”dest”: (str) 仅在页面上的目标位置未提供为“/XYZ”或未找到页码时才存在。
  

示例：

{
    '__bookmark_1': {'page': 0, 'to': (0.0, 541.0), 'zoom': 0.0},
    '__bookmark_2': {'page': 0, 'to': (0.0, 481.45), 'zoom': 0.0},
} 

或：

{
    '21154a7c20684ceb91f9c9adc3b677c40': {'page': -1, 'dest': '/XYZ 15.75 1486 0'},
    ...
} 

目录中所有在“/Dests”和“/Names/Dests”键下找到的名称都包含在内。

• v1.23.6 版中的新功能

page_cropbox(pno)

• v1.17.7 版中的新功能

仅适用于 PDF：返回未旋转的页面矩形 – 无需加载页面（通过 Document.load_page()）。这适用于需要最佳性能的内部目的。

参数：

pno (int) – 从 0 开始的页面编号。

返回：

页面的 Rect 与 Page.rect() 类似，但忽略任何旋转。

page_xref(pno)

• 新增于 v1.17.7

仅限 PDF：返回页面的 xref – 不加载页面（通过 Document.load_page()）。这是为内部需要而设计，要求尽可能最佳性能。

参数：

pno (int) – 基于 0 的页码数。

返回：

页面的 xref 与 Page.xref 类似。

pages(start=None[, stop=None[, step=None]])

• 新增于 v1.16.4

一个页面范围的生成器。参数的含义与内置函数 range() 相同。用于形如 “for page in doc.pages(start, stop, step): …” 的表达式。

参数：

• start (int) – 从此页码开始迭代。默认为零，允许的值为 -∞ < start < page_count。如果为负数，将在开始迭代之前加上 page_count。
  
• stop (int) – 在此页码数停止迭代。默认为 page_count，可选范围为 -∞ < stop <= page_count。大于此值的将被 静默替换 为默认值。负值将循环发出倒序页面。与内置的 range() 相同，这不是第一个不返回的页面。
  
• step (int) – 步进值。如果起始页小于结束页，默认为 1；如果起始页大于结束页，默认为 -1。不允许为零。
  

返回：

文档页面的生成器迭代器。以下是一些示例：

• ”doc.pages()” 发出所有页面。
  
• ”doc.pages(4, 9, 2)” 发出页面 4, 6, 8。
  
• ”doc.pages(0, None, 2)” 发出所有偶数编号的页面。
  
• ”doc.pages(-2)” 发出最后两页。
  
• ”doc.pages(-1, -1)” 以倒序方式发出所有页面。
  
• ”doc.pages(-1, -10)” 总是以倒序方式发出 10 页，从最后一页开始，重复，如果文档少于 10 页。因此，对于一个有 4 页的文档，将发出以下页码：3, 2, 1, 0, 3, 2, 1, 0, 3, 2, 1, 0, 3。
  

convert_to_pdf(from_page=-1, to_page=-1, rotate=0)

创建当前文档的 PDF 版本并将其写入内存。支持所有文档类型。参数的含义与 insert_pdf() 相同。实质上，您可以限制转换到页面子集，指定页面旋转并恢复页面顺序。

参数：

• from_page (int) – 要复制的第一页（基于 0）。默认为第一页。
  
• to_page (int) – 要复制的最后一页（基于 0）。默认为最后一页。
  
• rotate (int) – 旋转角度。默认为 0（无旋转）。应为整数 n 的 n * 90，未经检查。
  

返回类型：

bytes

返回：

一个 Python bytes 对象，包含一个 PDF 文件图像。内部使用 tobytes(garbage=4, deflate=True) 创建。参见 tobytes()。您可以直接将其输出到磁盘或打开为 PDF。以下是一些示例：

>>> # convert an XPS file to PDF
>>> xps = pymupdf.open("some.xps")
>>> pdfbytes = xps.convert_to_pdf()
>>>
>>> # either do this -->
>>> pdf = pymupdf.open("pdf", pdfbytes)
>>> pdf.save("some.pdf")
>>>
>>> # or this -->
>>> pdfout = open("some.pdf", "wb")
>>> pdfout.tobytes(pdfbytes)
>>> pdfout.close() 

>>> # copy image files to PDF pages
>>> # each page will have image dimensions
>>> doc = pymupdf.open()                     # new PDF
>>> imglist = [ ... image file names ...] # e.g. a directory listing
>>> for img in imglist:
 imgdoc=pymupdf.open(img)           # open image as a document
 pdfbytes=imgdoc.convert_to_pdf()  # make a 1-page PDF of it
 imgpdf=pymupdf.open("pdf", pdfbytes)
 doc.insert_pdf(imgpdf)             # insert the image PDF
>>> doc.save("allmyimages.pdf") 

注意

该方法与mutool convert CLI 使用相同的逻辑。在大多数情况下运行良好——但请注意以下限制。

• 图像文件：完美，未检测到问题。但是，图像透明度被忽略。如果需要（例如水印），请改用Page.insert_image()。否则，由于其更佳性能，建议使用此方法。
  
• XPS：外观非常好。链接工作正常，大纲（书签）丢失，但可以轻松恢复[2]。
  
• EPUB、CBZ、FB2：类似于 XPS。
  
• SVG：中等。与svglib大致相当。
  

get_toc(simple=True)

创建目录（TOC），以文档的大纲链为基础。

PyMuPDF 1.24.4 中文文档（七）（3）https://developer.aliyun.com/article/1559546