跳到內容
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；是否符合規範，仍須由檢查工具判定。

另請參閱

標題為「另請參閱」的區段