可选内容支持#
本文解释了PyMuPDF对PDF概念“可选内容”的支持。
介绍：可选内容概念#
可选内容在PDF中是一种根据特定条件显示或隐藏文档部分的方法：可以在使用支持的PDF消费者（查看器）或通过编程时，将参数设置为开启或关闭。
这个功能在诸如 CAD 图纸、分层艺术作品、地图和多语言文档等项目中非常有用。典型的用途包括显示或隐藏复杂矢量图形的细节，例如地理地图、技术设备、建筑设计等，包括在不同缩放级别之间自动切换。其他用例可能是在屏幕上显示文档时，自动显示不同的细节级别，而与打印时不同。
特殊的PDF对象，称为可选内容组（OCGs）用于定义这些不同的层内容。
将 OCG 分配给“普通”PDF对象（如文本或图像）会导致该对象可见或隐藏，具体取决于分配的 OCG 的当前状态。
为了简化PDF可选内容的整体配置定义，OCGs可以组织在更高级别的分组中，称为OC配置。每个配置都是一个OCGs的集合，以及每个OCG的期望初始可见状态。选择其中一个配置（通过PDF查看器或以编程方式）会导致文档中所有受影响的PDF对象的对应可见性变化。
除了默认的设置，OC 配置是可选的。
有关更多解释和背景信息，请参阅PDF规格手册。
PyMuPDF 对 PDF 可选内容的支持#
PyMuPDF 提供对查看、定义、修改和删除选项内容组、配置的全面支持，维护 OCG 的分配到 PDF 对象，并以编程方式在 OC 配置和每个单独 OCG 的可见状态之间切换。
如何添加可选内容#
这与向PDF添加一个可选内容组（Optional Content Group, OCG）一样简单： Document.add_ocg()。
如果之前的PDF根本没有OC支持，那么此时所需的设置（例如定义默认的OC配置）将自动完成。
该方法返回一个 xref，用于创建的 OCG。使用此 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并根据需要执行它。
当然，您的需求可能更复杂，涉及多个具有ON/OFF状态的OCG，它们通过某种逻辑关系连接 - 但这应该给您一个关于可能性及如何规划下一步的印象。