可选内容支持#
本文档解释了 PyMuPDF 对 PDF 概念 “可选内容” 的支持。
引言：可选内容概念#
PDF 中的可选内容是一种根据特定条件显示或隐藏文档部分的方法：这些参数在使用支持的可选内容的 PDF 阅读器（查看器）或通过编程方式时可以设置为“开启 (ON)”或“关闭 (OFF)”。
此功能在 CAD 图纸、分层图稿、地图和多语言文档等项目中有用。典型用途包括显示或隐藏复杂的矢量图形（如地理地图、技术设备、建筑设计等）的详细信息，包括自动切换不同的缩放级别。其他用例可能是在屏幕上显示文档时与打印时自动显示不同的细节级别。
特殊的 PDF 对象，即所谓的 可选内容组 (Optional Content Groups) (OCGs)，用于定义这些不同的层内容。
将 OCG 分配给“普通”PDF 对象（如文本或图像）将使该对象根据分配的 OCG 的当前状态可见或隐藏。
为了简化 PDF 可选内容的整体配置定义，OCGs 可以组织成更高级别的分组，称为 OC 配置 (OC Configurations)。每个配置都是 OCG 的集合，以及每个 OCG 所需的初始可见状态。选择其中一种配置（通过 PDF 阅读器或编程方式）会导致文档中所有受影响的 PDF 对象发生相应的可见性变化。
除了默认配置外，OC 配置是可选的。
有关更多解释和附加背景信息，请参阅 PDF 规范手册。
PyMuPDF 对 PDF 可选内容的支持#
PyMuPDF 全面支持查看、定义、更改和删除可选内容组、配置，以及维护 OCG 与 PDF 对象的分配关系，并通过编程方式在 OC 配置和每个 OCG 的可见状态之间切换。
如何添加可选内容#
这就像向 PDF 添加可选内容组 (Optional Content Group)，即 OCG 一样简单：Document.add_ocg()。
如果 PDF 之前完全没有可选内容支持，则此时会自动完成所需的设置（例如定义默认 OC 配置）。
该方法返回创建的 OCG 的 xref。使用此 xref 将任何 PDF 对象与之关联（标记），以便使其依赖于该 OCG 的状态。例如，您可以在页面上插入图像并按如下方式引用该 xref
img_xref = page.insert_image(rect, filename="image.file", oc=xref)
如果您想将一个现有图像置于 OCG 的控制下，您必须首先找到该图像的 xref 编号（在此处称为 img_xref），然后执行 doc.set_oc(img_xref, xref)。在此之后，如果 OCG 的状态分别是“开启 (ON)”或“关闭 (OFF)”，则该图像在整个文档中将可见或隐藏。您也可以使用此方法分配不同的 OCG。
要从图像中移除 OCG，请执行 doc.set_oc(img_xref, 0)。
一个 OCG 可以分配给多个 PDF 对象来控制它们的可见性。
如何定义复杂的可选内容条件#
可以建立复杂的逻辑条件来满足复杂的可见性需求。
例如，您可能希望创建一个多语言文档，以便用户可以根据需要切换语言。
请查看此 Jupyter Notebook 并按需执行。
当然，您的需求可能更加复杂，涉及多个 OCG，其开启/关闭状态通过某种逻辑关系连接 – 但它应该让您了解可能实现的功能以及如何规划下一步。