引言：分割PDF与目录管理的挑战
在处理大型pdf文档时，例如书籍或报告，我们经常需要将其分割成更小的、更易于管理的章节或部分。然而，简单的页面提取操作往往会丢失原始pdf中重要的导航信息——目录（table of contents, toc）。用户期望分割后的pdf文件也能拥有一个功能完整的、与其内容相对应的toc，以便于快速导航。pymupdf（也称为fitz）是一个功能强大的python库，能够高效地处理pdf文件，包括读取和设置toc。本文将深入探讨如何利用pymupdf实现这一目标，特别是如何处理toc的复杂结构规则。
PyMuPDF中的目录（TOC）机制
PyMuPDF通过Document.get_toc()方法获取PDF的目录，并通过Document.set_toc()方法设置目录。理解TOC的数据结构和其严格的规则是成功实现动态TOC生成的关键。
Document.get_toc()返回一个列表，其中每个元素都是一个子列表，表示一个TOC条目。每个子列表的结构为 [level, title, page]：
- level：一个整数，表示该TOC条目的层级（或缩进级别）。
- title：一个字符串，表示该TOC条目的标题。
- page：一个整数，表示该TOC条目对应的页面编号，注意这里是1-based索引。
TOC结构的关键规则：
Document.set_toc()方法对TOC列表的结构有严格要求。如果违反这些规则，TOC将无法正确设置或显示。主要规则包括：
- 首个条目必须为层级1（level = 1）：TOC列表的第一个条目必须以层级1开始。
-
后续层级变化规则：
- 后续条目的层级可以与前一个条目相等。
- 后续条目的层级可以比前一个条目正好高一级（例如，从层级1到层级2是合法的，但从层级1直接到层级3是非法的）。
- 后续条目的层级可以比前一个条目低（例如，从层级3到层级1是合法的）。
合法与非法TOC层级序列示例：
- 合法： [1, 1, 1, ...]
- 合法： [1, 2, 3, 3, 3, 1, ...]
- 非法： [1, 3, ...] (跳过了层级2)
这些规则对于我们动态生成TOC至关重要。当分割PDF时，我们提取的TOC子集可能不满足这些规则，特别是其第一个条目可能不是层级1，或者中间存在层级跳跃。
实现PDF分割与动态TOC生成
要实现带有动态TOC的PDF分割，我们需要一个多步骤的策略，以确保分割后的每个PDF文件都拥有符合PyMuPDF规则的TOC。
核心思路
- 获取原始TOC： 从原始PDF中提取完整的TOC。
- 筛选相关TOC条目： 根据指定的页码范围，从原始TOC中筛选出属于当前分割部分的条目。
- 调整页码： 将筛选出的TOC条目中的原始绝对页码转换为在新分割PDF中的相对页码。
- 调整层级合规性： 这是最关键的一步。根据PyMuPDF的TOC规则，对筛选并调整页码后的TOC条目进行层级修正，包括插入“虚拟”条目来满足层级1和层级连续性要求。
- 保存新PDF与TOC： 将修正后的TOC设置到新生成的PDF文件中，并保存。
辅助函数：调整TOC层级以符合规则
为了处理TOC层级规则，我们首先定义一个辅助函数_adjust_toc_for_rules。该函数将接收一系列TOC条目和一个起始相对页码，然后返回一个符合PyMuPDF规则的新TOC列表。
import fitz
import os
def _adjust_toc_for_rules(toc_entries, first_relative_page):
"""
调整TOC条目列表，使其符合PyMuPDF的set_toc()规则。
确保第一个条目是层级1，并维护有效的层级层次结构（例如，不允许1 -> 3的跳跃）。
Args:
toc_entries (list): 原始的、已筛选并调整页码的TOC条目列表。
每个条目为 [level, title, page] (page为1-based相对页码)。
first_relative_page (int): 新PDF中第一个实际内容的1-based相对页码。
用于填充虚拟条目的页码。
Returns:
list: 符合PyMuPDF规则的TOC条目列表。 
