Apache PDFBox多页面PDF结构标签失效问题排查求助

我正尝试使用Apache PDFBox创建可访问PDF并通过PAC测试。在社区帮助下第一页的结构标签已正常工作，但后续页面出现问题：第一页结构元素标签正常，新页面虽遵循相同逻辑创建结构元素并关联页面，标签却未生效。PAC测试中结构显示正常，但点击第二或第三页的标记内容时显示空白页面。

相关代码片段 #

创建新页面的代码

this.page = new PDPage(PDRectangle.A4);
document.addPage(page);
PDPageContentStream contentStream = new PDPageContentStream(document, page, PDPageContentStream.AppendMode.APPEND, true, true);
writeHinweis(font, hinweis);
// 根据页面、图片、注释类型设置setParentStructCounter
setParentStructCount(page);
addFontResource();

创建结构元素的代码

private PDStructureElement createPDStructureElement(String childElementType, PDStructureElement parentElement) {
    PDStructureElement pdStructureElement = new PDStructureElement(childElementType, parentElement);
    pdStructureElement.setPage(page);
    parentElement.appendKid(pdStructureElement);
    return pdStructureElement;
}

添加结构元素引用的代码

private PDMarkedContentReference erstellPDMarkedContentReference() {
    PDMarkedContentReference mcr = new PDMarkedContentReference();
    mcr.setPage(page); // 尝试添加此代码解决问题，单页时无需此代码
    mcr.setMCID(mcidCounter);
    return mcr;
}

创建标记内容字典的代码

private COSDictionary erstellMarkedContentDictionary(String altText) {
    COSDictionary markedContentDictionary = new COSDictionary();
    markedContentDictionary.setInt(COSName.MCID, mcidCounter);
    markedContentDictionary.setString(COSName.ALT, altText);
    markedContentDictionary.setName(COSName.S, "span"); // 尝试添加此代码修复问题
    markedContentDictionary.setItem(COSName.PAGE, page); // 尝试添加此代码修复问题
    return markedContentDictionary;
}

内容流中标记内容的起始与结束代码

contentStream.beginMarkedContent(COSName.P, PDPropertyList.create(dictionary));
// 内容流写入逻辑
contentStream.endMarkedContent();

其他关联代码

structureTreeRoot.setParentTreeNextKey(mcidCounter);
mcidCounter++;
structureElementArray.add(element);

绑定结构元素到结构树的代码

private void bindStructureTreeRootMitStructureElements() {
    COSDictionary parentTreeRoot = new COSDictionary();
    PDNumberTreeNode parentTree = new PDNumberTreeNode(parentTreeRoot, COSBase.class);

    Map<Integer, COSObjectable> parentTreeMap = new HashMap<>();
    parentTreeMap.put(0, structureElementArray);

    parentTree.setNumbers(parentTreeMap);
    structureTreeRoot.setParentTree(parentTree);
}

问题分析与解决方向 #

1. Parent Tree未按页面分组 #

你的bindStructureTreeRootMitStructureElements方法将所有结构元素统一绑定到键0的条目，但PDF的Parent Tree需要按页面独立分组：每个页面的MCID（标记内容ID）对应自身的结构元素集合，键需关联页面的对象编号，而非全局用0。单页时此问题被掩盖，多页时后续页面的MCID无法映射到正确结构，导致点击标记内容无法定位页面。

2. MCID全局递增违反页面唯一性规则 #

MCID是页面内唯一的，而非全局唯一。当前用全局mcidCounter递增，会导致后续页面MCID与第一页冲突，PAC能识别结构但无法关联到对应页面内容。需为每个页面维护独立的MCID计数器，每个页面从0开始重新计数。

3. 结构元素未按页面隔离存储 #

当前所有结构元素存入同一个数组，没有按页面区分。正确逻辑应为：

• 用Map存储每个页面对应的结构元素列表
• Parent Tree的键对应页面的COSObject编号（通过page.getCOSObject().getObjectNumber()获取）
• 每个页面的MCID映射到自身的结构元素集合

4. 冗余的PAGE属性设置 #

erstellMarkedContentDictionary中添加COSName.PAGE属于多余操作，标记内容的页面关联通过结构元素的setPage(page)和Parent Tree映射实现，无需在标记字典重复设置。

修复步骤示例 #

1. 为每个页面维护独立的计数器与结构元素列表：

// 存储各页面的结构元素集合
private Map<PDPage, List<PDStructureElement>> pageStructureElements = new HashMap<>();
// 存储各页面的MCID计数器
private Map<PDPage, Integer> pageMcidCounter = new HashMap<>();

// 创建新页面时初始化
this.page = new PDPage(PDRectangle.A4);
document.addPage(page);
pageStructureElements.put(page, new ArrayList<>());
pageMcidCounter.put(page, 0);

2. 替换全局MCID为页面专属计数器：

// 获取当前页面的MCID
int currentMcid = pageMcidCounter.get(page);
// 使用currentMcid创建标记内容字典和MCR
pageMcidCounter.put(page, currentMcid + 1);

3. 重构Parent Tree绑定逻辑，按页面分组：

private void bindStructureTreeRootMitStructureElements() {
    COSDictionary parentTreeRoot = new COSDictionary();
    PDNumberTreeNode parentTree = new PDNumberTreeNode(parentTreeRoot, COSBase.class);
    Map<Integer, COSObjectable> parentTreeMap = new HashMap<>();

    for (Map.Entry<PDPage, List<PDStructureElement>> entry : pageStructureElements.entrySet()) {
        PDPage page = entry.getKey();
        List<PDStructureElement> elements = entry.getValue();
        // 用页面对象编号作为Parent Tree的键
        int pageObjNum = page.getCOSObject().getObjectNumber();
        parentTreeMap.put(pageObjNum, new COSArray(elements));
    }

    parentTree.setNumbers(parentTreeMap);
    structureTreeRoot.setParentTree(parentTree);
    // 设置ParentTreeNextKey为最大MCID值+1，避免后续新增内容冲突
    int maxMcid = pageMcidCounter.values().stream().max(Integer::compare).orElse(0);
    structureTreeRoot.setParentTreeNextKey(maxMcid);
}

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