跳转到内容
NextPDF

从 HTML 制作具备无障碍性的标记式 PDF

概览

标题为“概览”的章节

本 recipe（范例）会从语义化 HTML 制作标记式 PDF。NextPDF 会输出逻辑结构树、文档目录中的语言信息以及 PDF/UA-2 标记。是否符合规范由检查工具判定。本范例依循 examples/31-pdfua2-tagged.php。

先决条件

标题为“先决条件”的章节
  • 已安装核心套件：composer require nextpdf/core:^3。
  • 准备一套用于验证步骤的 PDF/UA 验证工具。本范例使用 veraPDF。

范例

标题为“范例”的章节
  1. 创建文档。
  2. 调用 enableTaggedPdf() 并传入 BCP-47 语言标记，且务必先于调用 writeHtml()。HTML 管线在构建 parser（解析器）时会检测标记模式，并连接标记内容输出器。
  3. 设置文档元数据（标题、语言）。setLanguage() 与 enableTaggedPdf() 一起使用时是幂等的。
  4. 写入语义化 HTML。解析器会将每个区块元素映射为一个结构元素：h1 映射到 H1、p 映射到 P、ul/li 映射到 L/LI、table 映射到 Table/TR/TD。
  5. 保存文件，接着用 PDF/UA 检查工具验证。

完整范例

标题为“完整范例”的章节
<?php


declare(strict_types=1);


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


use NextPDF\Core\Document;


$doc = Document::createStandalone();


// Step 2 — enable tagged mode BEFORE writeHtml(). The lang argument
// drives the catalog /Lang entry and the structure tree root language.
$doc->enableTaggedPdf(lang: 'en');


// Step 3 — metadata. setLanguage() restates intent; it is idempotent here.
$doc->setTitle('Accessible Report');
$doc->setLanguage('en');


$doc->addPage();


// Step 4 — semantic HTML. Each block element becomes a StructElem; text
// runs are wrapped in BDC/EMC operators with stable MCIDs.
$html = <<<'HTML'
<h1>Quarterly Accessibility Report</h1>
<p>This document opts into tagged PDF so assistive technology can expose
a meaningful reading order.</p>
<h2>Findings</h2>
<ul>
  <li>Headings carry semantic roles.</li>
  <li>Lists keep their item structure.</li>
</ul>
HTML;


$doc->writeHtml($html);


$doc->save(__DIR__ . '/accessible.pdf');


echo "Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf\n";

预期输出

标题为“预期输出”的章节
Wrote accessible.pdf — validate with: verapdf --flavour ua2 accessible.pdf

输出结果会包含结构树、/MarkInfo << /Marked true >>、目录中的 /Lang 项目，以及 pdfuaid:part 这个 XMP 标记。运行检查工具，确认这些项目都存在且内部一致。

边界情境

标题为“边界情境”的章节
  • 调用顺序。 如果 enableTaggedPdf() 晚于 writeHtml() 调用，不会回头为已写入的内容补上标记。请先启用标记模式。
  • 语言标记。 将 ConformancePolicy::strictUa2() 作为第二个参数传入，可在 API 边界直接拒绝格式错误的 BCP-47 标记，而不是在写入时静默丢弃。
  • 幂等的重新启用。 调用两次 enableTaggedPdf() 只会更新语言，不会重建你已填入的结构树。
  • 手动标记。 对于非 HTML 内容，请使用 beginTag() / endTag() 将项目包起来。容器类型（Table、TR、L、LI）会成为不含标记内容的分组元素；叶节点类型（P、H1–H6、TD）则会获得 MCID。
  • 支持不等于符合规范。 NextPDF 会输出 PDF/UA-2 所需的结构性元数据。同时，它会发出降级对等性的警告：正式上线审批时，外部 oracle 验证仍由调用端负责。在你声明某个文件符合规范之前，请先运行检查工具。

一致性

标题为“一致性”的章节
声明规格条款参考 ID
真实内容需要逻辑结构。ISO 14289-2§8.2.2
结构元素遵循既定的嵌套关系与阅读顺序。ISO 14289-2§8.2.3

这个范例演示如何生成支持无障碍访问的标记式结构。它并未主张符合 PDF/UA-2；这一点要由检查工具判定。

另请参阅

标题为“另请参阅”的章节