PDF/UA-2（ISO 14289-2）規格對應

概覽

本頁將 NextPDF Core 的功能對應到 ISO 14289-2（PDF/UA-2）的條款。它說明這個函式庫能協助作者滿足哪些條款，以及哪些條款明確不在涵蓋範圍內。這並非符合性聲明。一份檔案是否符合要求，取決於作者內容、來源 markup（標記語言），以及透過外部 PDF/UA 檢查器進行的驗證。

安裝

composer require nextpdf/core

概念總覽

PDF/UA-2（ISO 14289-2）定義了無障礙 PDF 的相關要求。這些要求建立在 ISO 32000-2 §14.7 的邏輯結構機制，以及 ISO 32000-2 §14.9 的無障礙支援項目之上。一份符合要求的檔案會以 ISO 14289-2 §5 的識別結構描述標示自身。一份符合要求的檔案會帶有一棵結構樹，其根節點下只有單一的 Document 元素（ISO 14289-2 §8.2.5.2）。一份符合要求的檔案會使用標準結構類型，讓輔助科技能將每個標籤 resolve（解析）為已知的角色。

NextPDF 提供此模型撰寫所需的基礎元件：結構樹建構、標準角色對應、由語意化 HTML 產生的標記內容標籤，以及 BCP-47 語言屬性。NextPDF 不會推斷來源內容中缺少的語意。NextPDF 不會執行符合性檢查器。ISO 14289-2 §3.1 所描述、由輔助科技解讀結構樹的模型，正是這些基礎元件的設計目標。某份特定檔案是否滿足每一項條款，取決於作者輸入以及外部驗證器。

API 介面

條款領域	NextPDF 進入點
標記式 PDF 啟用、mark-info、目錄語言	`Document::enableTaggedPdf(string $lang, ?ConformancePolicy)`
文件層級的自然語言	`Document::setLanguage(string $lang)`
結構樹與單一 `Document` 根節點	`StructureTree::createRoot()`, `StructureTree::addElement()`
標準結構類型詞彙表	`RoleMap::standard()`
個別元素層級的語言、替代文字與取代文字	`StructureElement` 建構子屬性
BCP-47 嚴格驗證	`Bcp47Validator`, `ConformancePolicy::strictUa2()`
啟發式修補（選擇性啟用）	`AccessibilityAutoFixerRegistry`

程式碼範例 — 快速上手

<?php

declare(strict_types=1);

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->enableTaggedPdf(lang: 'en');
$doc->setTitle('PDF/UA-2 structure demonstration');
$doc->addPage();
$doc->writeHtml('<h1>Title</h1><p>Body.</p><ul><li>Item</li></ul>');
$doc->save(__DIR__ . '/output/ua2.pdf');

// Then validate with an external checker. NextPDF does not assert
// conformance on your behalf:
//   verapdf --flavour ua2 output/ua2.pdf

程式碼範例 — 正式環境

請參閱無障礙模組的正式環境範例，了解如何使用採用依賴注入的寫入器，搭配嚴格 BCP-47 驗證、建議性記錄與錯誤處理。同樣的接線方式也適用於 PDF/UA-2 撰寫流程。唯一需要新增的，是產生後的外部驗證步驟。此步驟對符合性聲明而言是必要的，且屬於呼叫端的責任。

邊界情況與陷阱

依設計，啟用了標記式 PDF 但未附加任何結構子節點的文件，不會宣告 PDF/UA-2 識別區塊（ISO 14289-2 §5）。空的結構樹會被驗證器拒絕。
同時呼叫 enablePdfA() 與 enableTaggedPdf() 時，會把單值的符合性判別欄位收斂為「後者覆蓋前者」，同時保留累加的結構性副作用。一則 CONFORMANCE_MODE_CLOBBERED 警告會讓這個情況可被觀察到。
ISO 14289-2 §7.2.2 允許一份符合要求的檔案額外宣告符合更廣泛的無障礙法規。NextPDF 僅輸出 PDF/UA-2 識別結構描述，不會輸出其他法規聲明的中繼資料。

條款對應與明確未涵蓋項目

條款領域（ISO 14289-2 / ISO 32000-2）	NextPDF 支援程度	備註
PDF/UA-2 識別結構描述（ISO 14289-2 §5）	支援	僅在結構樹具有子節點時才會輸出。
結構樹根節點下的單一 `Document` 元素（ISO 14289-2 §8.2.5.2；ISO 32000-2 §14.7.2）	支援	`createRoot()` 會強制只能有單一的根 `Document`。
標準結構類型與角色對應（ISO 32000-2 §14.7；Well-Tagged PDF §8.2.5.1）	支援	`RoleMap::standard()` 再加上 PDF 2.0 命名空間。
標記內容序列與父節點樹（ISO 32000-2 §14.7.2）	支援	個別頁面的識別碼、跨頁延續。
目錄與個別元素層級的自然語言（ISO 32000-2 §14.9；ISO 14289-2 §8.4.4）	支援	BCP-47；嚴格模式會拒絕格式不正確的標籤。
替代文字與取代文字的載體（ISO 32000-2 §14.9）	支援該載體；內容由作者提供	此函式庫不會產生替代文字。
邏輯閱讀順序（ISO 32000-2 §14.7）	支援來源順序；不會重新排序	修正後的閱讀順序屬於作者的責任。
表格標題關聯與範圍	超出 HTML 標記語言的部分不在涵蓋範圍內	不會推斷；取決於來源標記語言。
標題層級正確性與大綱	不在涵蓋範圍內	作者必須提供正確的標題階層。
端對端 PDF/UA-2 驗證	不在涵蓋範圍內	未內建檢查器；請於外部驗證。
符合性證明或認證	不在涵蓋範圍內	此函式庫不提供。

效能

結構樹機制只會對元素集合額外進行一次線性序列化處理；其成本主要來自 HTML 管線，而非標籤輸出。performance_budget 上限適用於一份典型的多頁語意化文件。

安全性注意事項

語言與無障礙屬性的值，在進入 PDF 物件語法之前會先經由 PdfStringEscaper 跳脫處理，而嚴格模式的 BCP-47 驗證會在 API 邊界收窄語言標籤的輸入面。請將作者提供的替代文字與標題視為不受信任的輸出。

符合性

NextPDF 輸出的結構，與 ISO 14289-2 及 ISO 32000-2 §14.7 所定義的 PDF/UA-2 結構樹模型一致。它並不主張某份特定檔案符合 PDF/UA-2。請以 PDF/UA 檢查器（例如 veraPDF）驗證；此函式庫不會代你主張符合性。內建的 veraPDF UA-2 golden 測試在 veraPDF 執行檔不存在時會被 skip-gate 略過，因此這裡並未聲明任何符合性通過。引用的條款一律以改寫呈現，絕不引述原文；chunk 雜湊值記錄於 docs/public/modules/core/_normative-evidence-a11y.md 一檔中。

已知限制

一項 PDF/UA-2 符合性聲明，需要作者提供的語意（替代文字、正確的標題階層、表格標題關聯、預期的閱讀順序、裝飾性內容分類），再加上以外部檢查器進行的驗證。這些項目都不是由此函式庫產生或驗證的。執行階段會發出一則 Degraded / ComplianceRisk 建議訊息，引導呼叫端在正式環境簽核前先於外部進行驗證。符合性是最終檔案與撰寫流程的性質，而非呼叫 API 的結果。