如何使用Pymupdf为PDF添加书签 并为高亮文本绑定对应书签

PyMuPDF（导入时模块名为fitz）原生支持PDF目录操作和标注添加功能，无需依赖PyPDF2即可完整实现需求。

前置准备 #

安装依赖包：

pip install pymupdf

建议使用1.20.0及以上版本，API兼容性更好。

完整实现代码 #

import fitz

def add_highlight_with_bookmark(input_pdf_path, output_pdf_path, target_text_list, top_bookmark_name=None):
    # 打开PDF文档
    doc = fitz.open(input_pdf_path)
    # 获取文档现有目录，无目录则返回空列表
    toc = doc.get_toc()

    # 可按需添加顶级父书签
    if top_bookmark_name:
        # 目录项格式：[层级, 书签名称, 跳转页码(从1开始), 跳转坐标]
        toc.append([1, top_bookmark_name, 1])
    
    for target_text in target_text_list:
        # 遍历所有页面搜索目标文本
        for page_idx in range(doc.page_count):
            page = doc.load_page(page_idx)
            # 搜索当前页所有匹配的文本位置
            match_rect_list = page.search_for(target_text)
            for match_idx, rect in enumerate(match_rect_list):
                # 1. 给匹配文本添加高亮标注
                highlight_annot = page.add_highlight_annot(rect)
                highlight_annot.update()

                # 2. 构造书签名，同页重复文本加序号区分
                if len(match_rect_list) > 1:
                    bookmark_title = f"{target_text}_{match_idx + 1}"
                else:
                    bookmark_title = target_text
                
                # 添加子级书签，跳转至高亮位置左上角
                toc.append([
                    2, 
                    bookmark_title, 
                    page_idx + 1,  # 目录页码从1开始，和阅读器显示一致
                    fitz.Point(rect.x0, rect.y0)
                ])
    
    # 写入更新后的目录
    doc.set_toc(toc)
    # 保存修改后的PDF
    doc.save(output_pdf_path)
    doc.close()

# 调用示例
if __name__ == "__main__":
    add_highlight_with_bookmark(
        input_pdf_path="你的原文件路径.pdf",
        output_pdf_path="添加高亮书签_输出.pdf",
        target_text_list=["需要高亮的文本1", "需要高亮的文本2", "测试关键词"],
        top_bookmark_name="高亮内容索引"
    )

调整说明 #

• 仅需添加普通书签无需高亮的场景：直接构造toc列表调用doc.set_toc()即可，无需处理高亮标注逻辑
• 书签层级调整：修改目录项第一个数值即可，数值越大层级越深，1为顶级书签
• 高亮样式调整：可通过highlight_annot.set_colors(stroke=(1,1,0))修改高亮颜色，参数为RGB浮点值，取值范围0~1
• 页码规则：代码中加载页面的page_idx从0开始计数，目录项填写的页码需从1开始计数，和PDF阅读器显示页码一致

内容的提问来源于stack exchange，提问作者Nayana Madhu