如何用pypdf/pikepdf构建/StructTreeRoot标签且不破坏PDF视觉内容

我正在开发Python FastAPI后端，为Adobe InDesign生成的现有PDF注入WCAG 2.1无障碍合规标签，要求完全不改动文档布局与视觉二进制字节。目前已通过pypdf的PdfWriter.add_metadata成功注入全局元数据，但生成的PDF因缺少内部逻辑结构树/StructTreeRoot而无法通过无障碍检查。

以下是最小化Python实现代码：

from pypdf import PdfReader, PdfWriter

def inject_tags(input_pdf_path, output_pdf_path):
    reader = PdfReader(input_pdf_path)
    writer = PdfWriter()
    
    # 克隆视觉布局，不做任何修改
    for page in reader.pages:
        writer.add_page(page)
        
    # 全局元数据注入正常
    writer.add_metadata({
        '/Title': 'Accessible Document',
        '/Language': 'en-US'
    })
    
    # 问题：如何程序化建立/StructTreeRoot字典
    # 并将结构标签（如标题或图片的/Alt文本）映射到现有内容，同时不破坏原始布局流？
    
    with open(output_pdf_path, "wb") as out_file:
        writer.write(out_file)

inject_tags("input.pdf", "output.pdf")

Adobe Acrobat Pro的无障碍检查器提示缺少文档结构树，请问如何在pypdf（或pikepdf等互补库）中手动初始化/StructTreeRoot、/StructElem等底层PDF字典，将标签绑定到页面现有视觉元素？

一、使用pypdf手动构建结构树 #

pypdf对PDF结构树的原生支持有限，但可通过直接操作底层PDF对象手动创建/StructTreeRoot及关联元素，步骤如下：

1. 初始化结构树根节点
   创建包含必要条目的/StructTreeRoot字典：

   from pypdf.generic import DictionaryObject, ArrayObject, NameObject, TextStringObject
   
   # 创建结构树根
   struct_tree_root = DictionaryObject()
   struct_tree_root[NameObject("/Type")] = NameObject("/StructTreeRoot")
   struct_tree_root[NameObject("/K")] = ArrayObject()  # 存储顶级结构元素
   struct_tree_root[NameObject("/RoleMap")] = DictionaryObject()  # 可选：自定义标签到标准角色的映射
   

2. 创建结构元素并绑定内容
   利用内容块的MCID（内容标识符）将结构标签关联到页面现有内容。假设已获取目标内容的MCID，可创建对应结构元素：

   # 示例：创建H1标题结构元素
   heading_elem = DictionaryObject()
   heading_elem[NameObject("/Type")] = NameObject("/StructElem")
   heading_elem[NameObject("/S")] = NameObject("/H1")  # WCAG标准标题角色
   heading_elem[NameObject("/P")] = struct_tree_root  # 父节点为结构树根
   heading_elem[NameObject("/K")] = 0  # 绑定到MCID为0的内容块
   
   # 图片元素添加替代文本示例
   # img_elem = DictionaryObject()
   # img_elem[NameObject("/Type")] = NameObject("/StructElem")
   # img_elem[NameObject("/S")] = NameObject("/Figure")
   # img_elem[NameObject("/P")] = struct_tree_root
   # img_elem[NameObject("/K")] = 1  # 绑定到MCID为1的图片
   # img_elem[NameObject("/Alt")] = TextStringObject("这是一张示例图片的替代文本")
   
   # 将元素添加到结构树根的子元素数组
   struct_tree_root[NameObject("/K")].append(heading_elem)
   

3. 关联结构树到文档与页面
   将结构树根添加到PDF目录，并为页面设置/StructParents条目：

   # 把结构树根写入writer的目录对象
   writer._root_object[NameObject("/StructTreeRoot")] = struct_tree_root
   
   # 为每个页面关联结构树根
   for page in writer.pages:
       page[NameObject("/StructParents")] = 0
   

二、使用pikepdf（更便捷的底层操作） #

pikepdf对PDF对象的操作更直观，适合快速构建结构树，示例代码如下：

import pikepdf

def inject_tags_with_pikepdf(input_pdf_path, output_pdf_path):
    with pikepdf.open(input_pdf_path) as pdf:
        # 设置全局元数据
        pdf.docinfo.Title = "Accessible Document"
        pdf.docinfo.Language = "en-US"

        # 创建结构树根
        struct_tree_root = pikepdf.Dictionary(
            Type=pikepdf.Name.StructTreeRoot,
            K=pikepdf.Array(),
            RoleMap=pikepdf.Dictionary()
        )

        # 示例：创建H1标题元素，绑定到MCID=0的内容
        h1_elem = pikepdf.Dictionary(
            Type=pikepdf.Name.StructElem,
            S=pikepdf.Name.H1,
            P=struct_tree_root,
            K=0
        )

        # 图片元素添加替代文本示例
        # img_elem = pikepdf.Dictionary(
        #     Type=pikepdf.Name.StructElem,
        #     S=pikepdf.Name.Figure,
        #     P=struct_tree_root,
        #     K=1,
        #     Alt=pikepdf.String("示例图片的替代文本")
        # )
        # struct_tree_root.K.append(img_elem)

        struct_tree_root.K.append(h1_elem)

        # 将结构树关联到文档根目录
        pdf.Root.StructTreeRoot = struct_tree_root

        # 为所有页面设置结构父节点
        for page in pdf.pages:
            page.StructParents = 0

        # 保存时保留原始PDF属性（如PDF/A）
        pdf.save(output_pdf_path, preserve_pdfa=True)

inject_tags_with_pikepdf("input.pdf", "output.pdf")

关键注意事项 #

• MCID获取：要绑定标签到具体内容，需先解析页面内容流，提取每个内容块的MCID（内容流中以/MCID标记的标识符）。可通过pypdf的page.get_contents()或pikepdf的page.contents解析内容操作符获取。
• 布局保护：上述操作仅添加结构树与元数据，不修改页面内容流或视觉元素，满足不改动布局的要求。
• WCAG合规：使用标准PDF结构角色（如/H1-/H6、/Paragraph、/Figure等），并为非文本元素添加/Alt文本。

内容的提问来源于stack exchange，提问作者Leonildo Gomes