標記式 PDF（Accessibility）

Accessibility 模組（StructureTreeManager、RoleMap、TaggedContentManager）負責產生標記式 PDF 輸出，讓螢幕閱讀器與輔助科技能正確解讀文件結構。啟用後，所有內容都會被包裹在描述語意角色的結構元素中。

快速參考

方法	說明
setTaggedPdf()	啟用或停用標記式 PDF 模式
setLanguage()	設定文件主要語言（BCP 47）
openTag()	開啟一個標記結構元素
closeTag()	關閉一個標記結構元素
image(..., alt:)	新增帶替代文字的圖片

啟用標記式 PDF

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setLanguage('zh-TW')
    ->addPage()
    ->setFont('Helvetica', '', 12);

呼叫 setTaggedPdf(true) 後，StructureTreeManager 會延遲初始化，並在 PDF Catalog 中寫入 MarkInfo 字典（Marked = true）。

結構元素

TCPDF-Next 支援完整的 PDF 2.0 標準標籤集：

類別	標籤
群組	Document, Part, Sect, Div, BlockQuote, Caption, NonStruct
標題	H1, H2, H3, H4, H5, H6
段落	P, Span
清單	L, LI, Lbl, LBody
表格	Table, TR, TH, TD, THead, TBody, TFoot
行內	Link, Em, Strong, Code
插圖	Figure, Formula, Form

基本標記

$pdf->openTag('H1')
    ->cell(0, 10, '2026 年度報告', newLine: true)
    ->closeTag('H1')
    ->openTag('P')
    ->multiCell(0, 6, '本文件展示標記式 PDF 輸出，以符合無障礙合規要求。')
    ->closeTag('P')
    ->save('tagged-basic.pdf');

標籤必須正確巢狀。StructureTreeManager 會驗證巢狀結構，若不匹配會拋出例外。

標記式表格

$pdf->openTag('Table')
    ->openTag('TR')
    ->openTag('TH')->cell(50, 8, '季度')->closeTag('TH')
    ->openTag('TH')->cell(50, 8, '營收')->closeTag('TH')
    ->closeTag('TR')
    ->openTag('TR')
    ->openTag('TD')->cell(50, 8, 'Q1')->closeTag('TD')
    ->openTag('TD')->cell(50, 8, '$1,200,000')->closeTag('TD')
    ->closeTag('TR')
    ->closeTag('Table');

圖片替代文字

開啟標籤時可傳入 Alt、ActualText、Lang、Title 等屬性：

$pdf->openTag('Figure', ['Alt' => '公司商標', 'ActualText' => 'Acme Corp Logo'])
    ->image('/path/to/logo.png', 10, 50, 40, 40)
    ->closeTag('Figure');

image() 方法也接受 alt 參數作為簡寫 — $pdf->image('chart.png', 10, 80, 120, 60, alt: '營收圖表') 會自動將圖片包裹在 Figure 標籤中。

角色對應

RoleMap 將自訂標籤名稱對應到標準 PDF 結構類型，讓你能使用領域特定名稱同時維持 PDF/UA 相容性：

$pdf->openTag('Invoice', ['roleMap' => 'Sect'])
    ->openTag('LineItem', ['roleMap' => 'P'])
    ->cell(0, 8, 'Widget x 10 — $500.00', newLine: true)
    ->closeTag('LineItem')
    ->closeTag('Invoice');

角色對應會寫入結構樹根節點，讓驗證工具能將自訂標籤解析為標準等效類型。若需處理多語言內容，可在元素層級覆寫語言：->openTag('P', ['Lang' => 'en-US'])。

PDF/UA 合規需求

要產生完全符合 PDF/UA 規範的文件，請確保：

1. 啟用標記式 PDF — setTaggedPdf(true)
2. 設定文件語言 — setLanguage('zh-TW')
3. 所有內容都已標記 — 結構元素外不可有未標記的內容
4. 所有圖片都有替代文字 — 透過 alt: 參數或 Figure 標籤的 Alt 屬性
5. 表格使用 TH 標記表頭 — 表頭儲存格必須與資料儲存格區分
6. 字型已嵌入 — TCPDF-Next 預設嵌入所有字型

與 PDF/A-4 的整合

標記式 PDF 與 PDF/A-4 完全相容。同時啟用即可產生兼具存檔與無障礙特性的文件：

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setPdfA(true)
    ->setLanguage('zh-TW')
    ->setTitle('無障礙存檔文件')
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->openTag('H1')
    ->cell(0, 10, 'PDF/A-4 + PDF/UA 文件', newLine: true)
    ->closeTag('H1')
    ->save('accessible-archival.pdf');