PDF/UA-2（ISO 14289-2）规范映射

概览

本页将 NextPDF Core 的功能映射到 ISO 14289-2（PDF/UA-2）的相关条款。它说明该库可协助作者满足哪些条款，以及哪些条款明确不在涵盖范围内。这不是符合性声明。一份文档能否具备符合性，取决于作者提供的内容、来源 markup（标记语言），以及通过外部 PDF/UA 检查器完成的验证。

安装

composer require nextpdf/core

概念综述

PDF/UA-2（ISO 14289-2）定义了无障碍 PDF 的相关要求。这些要求建立在 ISO 32000-2 §14.7 的逻辑结构机制，以及 ISO 32000-2 §14.9 的无障碍支持项之上。具备符合性的文件会通过 ISO 14289-2 §5 的识别结构描述标识自身。具备符合性的文件会带有一棵结构树，其根节点下只有单一的 Document 元素（ISO 14289-2 §8.2.5.2）。具备符合性的文件会使用标准结构类型，让辅助技术能够将每个标签 resolve（解析）为已知角色。

NextPDF 提供实现此模型所需的编写基础组件：结构树构建、标准角色对应、由语义化 HTML 生成的标记内容标签，以及 BCP-47 语言属性。NextPDF 不会推断来源内容中缺失的语义。NextPDF 不会运行符合性检查器。ISO 14289-2 §3.1 所描述的、由辅助技术处理结构树的模型，正是这些基础组件的设计目标。某份特定文件是否满足每一项条款，取决于作者输入以及外部验证器。

API 接口

条款领域	NextPDF 入口点
标记式 PDF 启用、mark-info、目录语言	`Document::enableTaggedPdf(string $lang, ?ConformancePolicy)`
文档级别的自然语言	`Document::setLanguage(string $lang)`
结构树与单一 `Document` 根节点	`StructureTree::createRoot()`, `StructureTree::addElement()`
标准结构类型词汇表	`RoleMap::standard()`
单个元素级别的语言、替代文本与替换文本	`StructureElement` 构造函数属性
BCP-47 严格验证	`Bcp47Validator`, `ConformancePolicy::strictUa2()`
启发式修复（选择性启用）	`AccessibilityAutoFixerRegistry`

代码示例 — 快速上手

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->enableTaggedPdf(lang: 'en');
$doc->setTitle('PDF/UA-2 structure demonstration');
$doc->addPage();
$doc->writeHtml('<h1>Title</h1><p>Body.</p><ul><li>Item</li></ul>');
$doc->save(__DIR__ . '/output/ua2.pdf');

// Then validate with an external checker. NextPDF does not assert
// conformance on your behalf:
//   verapdf --flavour ua2 output/ua2.pdf

代码示例 — 生产环境

请参阅无障碍模块的生产环境示例，了解采用依赖注入的写入器如何配合严格 BCP-47 验证、建议性日志记录与错误处理。同样的装配方式也适用于 PDF/UA-2 编写流程。唯一需要新增的是生成后的外部验证步骤。此步骤对符合性声明而言是必需的，且由调用方负责。

边界情况与陷阱

按设计，启用了标记式 PDF 但未附加任何结构子节点的文档，不会声明 PDF/UA-2 识别区块（ISO 14289-2 §5）。空的结构树会被验证器拒绝。
同时调用 enablePdfA() 与 enableTaggedPdf() 时，会将单值的符合性判别字段归并为「后者覆盖前者」，同时保留累加产生的结构性副作用。这个情况会通过一条 CONFORMANCE_MODE_CLOBBERED 警告暴露出来。
ISO 14289-2 §7.2.2 允许具备符合性的文档额外声明其符合更广泛的无障碍法规。NextPDF 仅输出 PDF/UA-2 识别结构描述，不会输出其他法规声明的元数据。

条款对应与明确未涵盖项

条款领域（ISO 14289-2 / ISO 32000-2）	NextPDF 支持程度	备注
PDF/UA-2 识别结构描述（ISO 14289-2 §5）	支持	仅当结构树具有子节点时才会输出。
结构树根节点下的单一 `Document` 元素（ISO 14289-2 §8.2.5.2；ISO 32000-2 §14.7.2）	支持	`createRoot()` 会强制只能有单一的根 `Document`。
标准结构类型与角色对应（ISO 32000-2 §14.7；Well-Tagged PDF §8.2.5.1）	支持	`RoleMap::standard()`，并使用 PDF 2.0 命名空间。
标记内容序列与父节点树（ISO 32000-2 §14.7.2）	支持	单页标识符与跨页延续。
目录与单个元素级别的自然语言（ISO 32000-2 §14.9；ISO 14289-2 §8.4.4）	支持	BCP-47；严格模式会拒绝格式不正确的标签。
替代文本与替换文本的载体（ISO 32000-2 §14.9）	支持该载体；内容由作者提供	该库不会生成替代文本。
逻辑阅读顺序（ISO 32000-2 §14.7）	支持来源顺序；不会重新排序	修正后的阅读顺序由作者负责。
表格标题关联与范围	超出 HTML 标记语言的部分不在涵盖范围内	不会推断；取决于来源标记语言。
标题级别正确性与大纲	不在涵盖范围内	作者必须提供正确的标题层级。
端到端 PDF/UA-2 验证	不在涵盖范围内	没有内置检查器；请在外部验证。
符合性证明或认证	不在涵盖范围内	该库不提供。

性能

结构树机制只会对元素集合额外执行一次线性序列化处理；成本主要来自 HTML 管线，而不是标签输出。performance_budget 上限适用于一份典型的多页语义化文档。

安全性注意事项

语言与无障碍属性的值在进入 PDF 对象语法之前，会先经过 PdfStringEscaper 转义处理；严格模式的 BCP-47 验证则会在 API 边界收窄语言标签的输入范围。请将作者提供的替代文本与标题视为不可信输出内容。

符合性

NextPDF 输出的结构，与 ISO 14289-2 及 ISO 32000-2 §14.7 所定义的 PDF/UA-2 结构树模型一致。它并不声称某份特定文档符合 PDF/UA-2。请使用 PDF/UA 检查器（例如 veraPDF）验证；此库不会代你作出符合性主张。内置的 veraPDF UA-2 golden 测试在 veraPDF 可执行文件不存在时会被 skip-gate 跳过，因此这里并未声明任何符合性通过。引用的条款一律以改写呈现，绝不引述原文；chunk 哈希值记录于 docs/public/modules/core/_normative-evidence-a11y.md 一文中。

已知限制

一项 PDF/UA-2 符合性声明，需要作者提供的语义（替代文本、正确的标题层级、表格标题关联、预期的阅读顺序、装饰性内容分类），并且需要通过外部检查器进行验证。这些项都不是由此库生成或验证的。运行时会发出一条 Degraded / ComplianceRisk 建议消息，引导调用方在生产环境审批前先进行外部验证。符合性是最终文档与编写流程的性质，而不是调用 API 的结果。