PDF/UA-2 符合性：NextPDF 面向 ISO 14289-2 输出的标记结构

概览

界线声明。 NextPDF 输出可支持无障碍创作的标记结构；它并不主张符合 PDF/UA-2，而是由检查器（checker）来判定。

PDF/UA-2 即 ISO 14289-2:2024，是叠加在标记式 PDF 2.0 之上的无障碍配置文件。NextPDF Core 会输出结构树、标记内容、catalog/structure 语言，以及 pdfuaid 标记——该标记由 Document::enableTaggedPdf() 写入。库会生成这个无障碍结构；至于是否符合，则由 PDF/UA 检查器（例如 verapdf --flavour ua2）决定。ISO 14289-2 §8.1 将符合性界定为文件必须满足的一组文件格式要求——由检查器评估，而非生产端自行声明。

安装

composer require nextpdf/core:^3

PDF/UA-2 标记是 Core 提供的能力（security.tagged_pdf）。标记结构本身不需要任何 Premium 套件。

概念总览

Document::enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null) 会设定 ConformanceMode::PdfUa2 并接上 TaggedContentEmitter。这个模式是「文件是否已按规范标记」的唯一可信来源；写入器随后会满足 ISO 14289-2 要求的结构义务：

真实内容均已标记——§8.2.2：每一段真实（非 artifact）内容都会纳入逻辑结构；artifact 则明确标示为 artifact。这建立在 ISO 32000-2 §14.7 标记式 PDF 结构（StructTreeRoot、结构元素、MCID）之上。
已声明自然语言——§8.4.4：文件以及语言切换处都带有 Lang。配合 ConformancePolicy::strictUa2() 时，格式错误的 BCP-47 标签会在 API 边界就被拒绝（fail-fast），而不是在写入时被静默丢弃。
图形带有替代描述——§8.5.1：每个 Figure 结构元素都有替代描述。
表格将表头与数据建立关联——§8.2.5.26：表格的 header/data 单元格关联会以结构方式表达。

NextPDF 会输出这些内容。它并不执行 §8.1 的符合性评估——那是检查器的职责，标准也将这项职责留给检查器。

API 接口

方法	效果
`enableTaggedPdf(string $lang = 'en', ?ConformancePolicy $policy = null): static`	设定 `ConformanceMode::PdfUa2`、接上 `TaggedContentEmitter`，并按策略验证 `$lang`。当策略要求验证 Lang 时，若 `$lang` 无效，会抛出 `InvalidConfigException`。
`beginTag()/endTag()`	为非 HTML 内容建立手动结构；容器类型会成为分组元素，叶节点类型则获得 MCID。
`ConformanceMode::requiresPdfUa2PageTabs(): bool`	对 `PdfUa2` 而言为 True——用于驱动 `/Tabs /S` 的页面强制要求。

代码示例——快速上手

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;
use NextPDF\Conformance\ConformancePolicy;

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/accessible.pdf';

$doc = Document::createStandalone();
$doc->enableTaggedPdf('en', ConformancePolicy::strictUa2()); // fail-fast Lang
$doc->setTitle('Accessible report 2026');
$doc->writeHtml('<h1>Quarterly report</h1><p>Body text.</p>'
    . '<img src="chart.png" alt="Revenue rose 12% quarter on quarter">');
$doc->save($out);

echo "Wrote {$out} — validate: verapdf --flavour ua2 {$out}\n";

代码示例——生产环境

生产环境中的 gate 会执行 verapdf --flavour ua2 out.pdf，并在报告违规项时让构建失败。集成测试 tests/Integration/Accessibility/VeraPdfUa2GoldenTest.php 会断言 HTML→标记式 PDF 的 golden fixture 通过 veraPDF UA-2（缺少 veraPDF 时则跳过）。检查器的判定就是这道 gate；输出器（emitter）的产物则是它的输入。

边界情况与注意事项

先启用。 enableTaggedPdf() 若在 writeHtml() 之后才调用，并不会回溯性地标记已写入的内容。
严格语言。 传入 ConformancePolicy::strictUa2()，可在 API 边界就拒绝格式错误的 BCP-47 标签，而不必等到后续 veraPDF 验证时才失败。
幂等重新启用。 调用两次只会更新语言，不会重建已写入内容的结构树。
空白标记文件。 空白的标记文件不会宣称符合 PDF/UA-2（EmptyTaggedPdfDoesNotAdvertisePdfUa2Test）——对于没有真实内容的文件，不会输出该标记，因此文件不会过度宣称。

性能

结构树的输出量与元素数量成正比。以一份典型报告为例，预算为墙钟时间 ≤ 1500 ms、峰值内存 ≤ 64 MB。

安全性说明

无障碍标记属于结构性信息，并非安全控制。它的设计本意就是把文件的逻辑结构暴露给辅助技术——标记树并不提供机密性保障。

PDF/UA-2 对应

PDF/UA-2 义务	ISO 14289-2 条款	NextPDF 输出
真实内容已在逻辑结构中标记	§8.2.2	`TaggedContentEmitter` + `StructureTree`
已声明文件/结构语言	§8.4.4	catalog `/Lang`，验证器为 `Bcp47Validator`
Figure 替代描述	§8.5.1	`alt` → `/Alt`（位于 Figure 元素上）
表格 header/data 关联	§8.2.5.26	由 HTML 表格产生的 TR/TH/TD 结构

标记 → ISO 32000-2 §14.9 交叉对照

PDF/UA-2 叠加在 ISO 32000-2 的标记式 PDF 模型之上。NextPDF 输出的结构元素会对应到 ISO 32000-2 §14.7 的逻辑结构（StructTreeRoot、结构元素、MCID）——chunk——以及为 PDF 2.0 定义的标准结构命名空间。角色对应表把 HTML 元素（h1、p、table）绑定到标准结构类型，让 UA-2 检查器能够识别它们。

WCAG 2.2 对应

标记结构是 WCAG 2.2 成功准则的技术基础——1.1.1（非文本替代，通过 §8.5.1 的 Figure /Alt）、1.3.1（信息与关联，通过结构树）以及 1.3.2（有意义的顺序，通过阅读顺序）。输出这个结构对 WCAG 符合性是必要但不充分的条件；作出该判定的是无障碍审计，而非库。

FIPS 模式行为

PDF/UA-2 的输出过程不执行任何密码学运算。FIPS 模式对标记结构路径没有任何影响。

符合性

主张	规范	条款
PDF/UA 版本由 `pdfuaid` schema 命名空间标识（表 1）。	ISO 14289-2	§5
符合 PDF/UA-2 会对文件施加一组必须满足的文件格式要求（由检查器评估符合性；生产端并不自行声明）。	ISO 14289-2	§8.1
真实内容必须在逻辑结构中标记。	ISO 14289-2	§8.2.2
文件的自然语言必须予以声明。	ISO 14289-2	§8.4.4
Figure 元素必须有替代描述。	ISO 14289-2	§8.5.1
表格结构必须将表头与数据单元格建立关联。	ISO 14289-2	§8.2.5.26
这个无障碍结构建立在 ISO 32000-2 标记式 PDF 的逻辑结构之上。	ISO 32000-2	§14.7.2

引用由 clause-id 加上 reference_id 指针组成，指向验证语料库。不会复现任何标准原文。