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）的產物則是檢查器的輸入。

邊界情況與注意事項

先啟用。 若在 writeHtml() 之後才呼叫 enableTaggedPdf()，它並不會回溯標記已寫入的內容。
嚴格語言。 傳入 ConformancePolicy::strictUa2()，即可在 API 邊界拒絕格式錯誤的 BCP-47 標籤，而不必等到事後的 veraPDF 驗證才失敗。
冪等重新啟用。 呼叫兩次只會更新語言，不會重建已填入內容的結構樹。
空白標記文件。 空白的標記文件不會宣稱符合 PDF/UA-2（EmptyTaggedPdfDoesNotAdvertisePdfUa2Test）——對於沒有真實內容的文件，NextPDF 不會輸出該標記，因此檔案不會過度宣稱。

效能

結構樹的輸出量會隨元素數量線性成長。以一份典型報告為例，預算為牆鐘時間 ≤ 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 指標表示，指向驗證語料庫。不會重製任何標準文字。