從 HTML 建立具無障礙性的標記式 PDF

概覽

這個 recipe（範例）會從語意化 HTML 建立標記式 PDF。NextPDF 會輸出邏輯結構樹、目錄語言，以及 PDF/UA-2 標記。是否符合規範，則由檢查工具判定。本範例依循 examples/31-pdfua2-tagged.php。

先決條件

已安裝核心套件：composer require nextpdf/core:^3。
一套用於驗證步驟的 PDF/UA 驗證工具。本範例使用 veraPDF。

範例

建立文件。
呼叫 enableTaggedPdf() 並傳入 BCP-47 語言標記，而且務必先於呼叫 writeHtml()。HTML 管線在建構 parser（剖析器）時，會偵測標記模式並接上標記內容的輸出器。
設定文件中繼資料（標題、語言）。setLanguage() 與 enableTaggedPdf() 並用時具有冪等性。
寫入語意化 HTML。剖析器會把每個區塊元素對映到一個結構元素：h1 對映到 H1、p 對映到 P、ul/li 對映到 L/LI、table 對映到 Table/TR/TD。
儲存檔案，接著用 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、THead、TBody、TFoot、TR、L、LI，以及群組元素 Sect/Div/Art/Aside/BlockQuote）會成為不含標記內容的群組元素；直接放在群組元素內的鬆散行內內容，會被包進一個合成的 P。葉節點類型（P、H1–H6、TD、TH）則會取得 MCID。
支援不等於符合規範。 NextPDF 會輸出 PDF/UA-2 所需的結構性中繼資料。它同時會發出降級對等性的警告：在正式上線簽核時，外部 oracle 驗證仍是呼叫端的責任。在你聲明某個檔案符合規範之前，請先執行檢查工具。
帶標記的 HTML 表格與群組元素皆可通過 veraPDF ua2。 帶標記的 <table>——無論是扁平的、含 colspan/rowspan 的、跨頁分頁的，或巢狀於儲存格中的——都會發出 Table/TR/TH/TD 結構（ISO 32000-2 §14.8；跨欄列的儲存格會帶上 Table 384 的 /ColSpan 與 /RowSpan 屬性），而群組元素 <section>/<div>/<article>/<aside>/<blockquote> 則會發出群組結構，其中鬆散的行內內容會被包進一個合成的 P。veraPDF --flavour ua2 對這些情境都回報零失敗。仍有一種情況會失敗：區塊元素巢狀於行內元素之內——例如連結內含標題，<a><h2>…</h2></a>——會觸發 Link shall not contain Hn，因此請把區塊內容放在行內包裹器之外。在你聲明某個檔案符合規範之前，請先執行檢查工具。

一致性

聲明	規格	條款
真實內容需要邏輯結構。	ISO 14289-2	§8.2.2
結構元素遵循既定的巢狀關係與閱讀順序。	ISO 14289-2	§8.2.3

這個範例示範如何產生支援無障礙撰寫的標記式結構。它並未主張符合 PDF/UA-2；是否符合規範，仍須由檢查工具判定。

從 HTML 建立具無障礙性的標記式 PDF

概覽

先決條件

範例

完整範例

預期輸出

邊界情境

一致性

另請參閱