Python批量读取、解析与写入PDF书签的完整指南

from pypdf import PdfReader

def build_page_index(reader):
    """建立 页面对象id -> 页码(从0开始) 的映射"""
    page_map = {}
    for i, page in enumerate(reader.pages):
        # id() 拿到的是 Python 对象身份，这里用间接引用更稳
        page_map[page.indirect_reference.idnum] = i
    return page_map

def walk_outline(reader, outline, page_map, depth=0, result=None):
    """递归遍历 Outline 树，收集标题/层级/目标页码"""
    if result is None:
        result = []
    if outline is None:
        return result
    for item in outline:
        # item 可能是嵌套 list（表示子节点），也可能是字典节点
        if isinstance(item, list):
            walk_outline(reader, item, page_map, depth + 1, result)
            continue
        title = item.get('/Title', '')
        page_no = -1
        try:
            # get_destination_page_number 是 pypdf 提供的便捷方法
            page_no = reader.get_destination_page_number(item)
        except Exception:
            page_no = -1
        result.append({
            'title': title,
            'depth': depth,
            'page': page_no
        })
    return result

reader = PdfReader("sample.pdf")
page_map = build_page_index(reader)
outline = reader.outline
bookmarks = walk_outline(reader, outline, page_map)
for bm in bookmarks:
    print("  " * bm['depth'], bm['title'], "->", bm['page'] + 1)

from pypdf import PdfReader, PdfWriter

def add_bookmarks(writer, bookmarks):
    """bookmarks: [{'title','page','depth'}, ...] 按阅读顺序排列"""
    # 用栈保存每一层的父节点，栈的深度即当前层级
    parent_stack = [None]
    for bm in bookmarks:
        depth = bm['depth']
        # 如果当前层级比栈浅，弹出多余的父节点
        while len(parent_stack) > depth + 1:
            parent_stack.pop()
        parent = parent_stack[-1]
        # 添加书签，parent 为 None 时挂在根上
        new_item = writer.add_outline_item(
            title=bm['title'],
            page_number=bm['page'],
            parent=parent
        )
        # 如果下一项是子节点，当前项要成为它的父
        if len(parent_stack) == depth + 1:
            parent_stack.append(new_item)
        else:
            parent_stack[depth + 1] = new_item
    return writer

reader = PdfReader("sample.pdf")
writer = PdfWriter()
writer.append(reader)  # 保留原文档全部页面
bookmarks = [
    {'title': '第 1 章 概述', 'page': 0, 'depth': 0},
    {'title': '1.1 背景', 'page': 1, 'depth': 1},
    {'title': '1.2 目标', 'page': 3, 'depth': 1},
    {'title': '第 2 章 方法', 'page': 5, 'depth': 0},
]
add_bookmarks(writer, bookmarks)
with open("output.pdf", "wb") as f:
    writer.write(f)

import os
import csv
from pypdf import PdfReader, PdfWriter

def load_bookmarks_from_csv(csv_path, page_offset=0):
    """读取 CSV，返回书签列表；页码统一转成 0 起始"""
    bookmarks = []
    with open(csv_path, newline='', encoding='utf-8-sig') as f:
        reader = csv.DictReader(f)
        for row in reader:
            bookmarks.append({
                'title': row['title'].strip(),
                'page': int(row['page']) - 1 + page_offset,
                'depth': int(row.get('depth', 0))
            })
    return bookmarks

def inject_bookmarks(pdf_path, bookmarks, out_path):
    reader = PdfReader(pdf_path)
    writer = PdfWriter()
    writer.append(reader)
    parent_stack = [None]
    for bm in bookmarks:
        depth = bm['depth']
        while len(parent_stack) > depth + 1:
            parent_stack.pop()
        parent = parent_stack[-1]
        new_item = writer.add_outline_item(
            title=bm['title'],
            page_number=bm['page'],
            parent=parent
        )
        if len(parent_stack) == depth + 1:
            parent_stack.append(new_item)
        else:
            parent_stack[depth + 1] = new_item
    with open(out_path, "wb") as f:
        writer.write(f)

def batch_process(src_dir, csv_dir, dst_dir, page_offset=0):
    os.makedirs(dst_dir, exist_ok=True)
    for name in os.listdir(src_dir):
        if not name.lower().endswith('.pdf'):
            continue
        pdf_path = os.path.join(src_dir, name)
        csv_path = os.path.join(csv_dir, os.path.splitext(name)[0] + '.csv')
        if not os.path.exists(csv_path):
            print(f"[跳过] 缺少目录文件: {name}")
            continue
        bookmarks = load_bookmarks_from_csv(csv_path, page_offset)
        out_path = os.path.join(dst_dir, name)
        try:
            inject_bookmarks(pdf_path, bookmarks, out_path)
            print(f"[完成] {name} 注入 {len(bookmarks)} 条书签")
        except Exception as e:
            print(f"[失败] {name}: {e}")

batch_process("./pdfs", "./csvs", "./output", page_offset=2)

def verify_bookmarks(reader, bookmarks, window=2):
    """校验书签标题是否能在目标页附近找到，返回可疑列表"""
    suspicious = []
    for bm in bookmarks:
        page_no = bm['page']
        if page_no < 0 or page_no >= len(reader.pages):
            suspicious.append((bm['title'], '页码越界'))
            continue
        # 在目标页前后 window 页范围内找标题
        found = False
        for offset in range(-window, window + 1):
            idx = page_no + offset
            if 0 <= idx < len(reader.pages):
                text = reader.pages[idx].extract_text() or ''
                if bm['title'][:8] in text:  # 取前8字降低匹配门槛
                    found = True
                    break
        if not found:
            suspicious.append((bm['title'], f'第{page_no+1}页附近未找到'))
    return suspicious