無障礙（PDF/UA）

★ Pro — Commercial License Required

PDF/UA 無障礙功能需要 Pro 套件。

TCPDF-Next Pro 提供完整的 PDF/UA（ISO 14289-2）支援，讓產生的 PDF 文件能被螢幕閱讀器與輔助技術正確解讀，服務視障及其他身心障礙使用者。

核心類別

類別	說明
StructureTreeManager	自動建構文件結構樹
RoleMap	自訂標籤名稱到標準結構類型的對應

啟用標記式 PDF

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setLanguage('zh-TW');

啟用後，StructureTreeManager 會自動追蹤所有結構標籤，在輸出時建構完整的結構樹。

結構元素

使用 openTag 和 closeTag 標記文件內容的語意結構：

$pdf->openTag('H1')
    ->cell(0, 10, '2026 年度報告', newLine: true)
    ->closeTag('H1')

    ->openTag('P')
    ->multiCell(0, 6, '本報告概述公司年度營運成果與財務狀況...')
    ->closeTag('P');

支援的結構元素

元素	用途	PDF/UA 要求
Document	根結構元素	必須
Part	文件主要區塊	選用
Sect	區段	選用
H1 -- H6	標題層級	必須按層級使用
P	段落	文字內容必須標記
Table	表格	必須包含 TH/TD
TR	表格列	必須在 Table 內
TH	表頭儲存格	資料表必須有表頭
TD	資料儲存格	必須在 TR 內
L	清單	必須包含 LI
LI	清單項目	必須在 L 內
Figure	圖片與圖表	必須有替代文字
Link	超連結	必須有連結文字
Span	行內內容	用於語言標記

RoleMap 角色對應

將自訂標籤名稱對應到標準 PDF 結構類型，提高程式碼的語意可讀性：

$pdf->setRoleMap([
    'invoice-header'  => 'H1',
    'line-item'       => 'TR',
    'item-desc'       => 'TD',
    'item-amount'     => 'TD',
    'summary'         => 'P',
    'company-logo'    => 'Figure',
]);

// 使用自訂標籤
$pdf->openTag('invoice-header')
    ->cell(0, 10, '發票明細', newLine: true)
    ->closeTag('invoice-header');

替代文字

所有非裝飾性圖片都必須提供替代文字，讓螢幕閱讀器能描述圖片內容：

$pdf->image(
    '/path/to/revenue-chart.png',
    x: 10, y: 50, width: 100, height: 80,
    alt: '營收圖表：第一季 120 萬、第二季 135 萬、第三季 142 萬、第四季 158 萬'
);

裝飾性圖片應標記為裝飾元素（artifact），使其不出現在結構樹中：

$pdf->artifact(function ($pdf) {
    $pdf->image('/path/to/decorative-border.png', x: 0, y: 0, width: 210);
});

語言標記

文件必須設定主要語言，並可對個別內容區塊標記不同語言：

$pdf->setLanguage('zh-TW');   // 文件主要語言

// 對特定段落標記不同語言
$pdf->openTag('P', ['lang' => 'en-US'])
    ->multiCell(0, 6, 'This section is in English.')
    ->closeTag('P');

$pdf->openTag('P', ['lang' => 'ja-JP'])
    ->multiCell(0, 6, 'このセクションは日本語です。')
    ->closeTag('P');

表格無障礙

資料表格必須有正確的表頭結構，讓螢幕閱讀器能建立儲存格與表頭的關聯：

$pdf->openTag('Table')
    ->openTag('TR')
        ->openTag('TH')->cell(40, 8, '品名')->closeTag('TH')
        ->openTag('TH')->cell(30, 8, '數量')->closeTag('TH')
        ->openTag('TH')->cell(30, 8, '金額')->closeTag('TH')
    ->closeTag('TR')
    ->openTag('TR')
        ->openTag('TD')->cell(40, 8, 'Widget A')->closeTag('TD')
        ->openTag('TD')->cell(30, 8, '100')->closeTag('TD')
        ->openTag('TD')->cell(30, 8, 'NT$ 5,000')->closeTag('TD')
    ->closeTag('TR')
    ->closeTag('Table');

結合 PDF/A-4 與 PDF/UA

建立同時符合歸檔與無障礙標準的文件：

use Yeeefang\TcpdfNext\Pro\Archive\PdfAManager;
use Yeeefang\TcpdfNext\Pro\Archive\PdfAVersion;

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setLanguage('zh-TW');

$manager = new PdfAManager($pdf);
$manager->enable(PdfAVersion::A4);
$manager->setOutputIntent(/* ... */);

// 文件同時符合 PDF/A-4 與 PDF/UA-2
$pdf->addPage()
    ->openTag('H1')
    ->font('Helvetica', size: 18)
    ->cell(0, 10, '無障礙歸檔文件', newLine: true)
    ->closeTag('H1')
    ->save('/output/pdfa4-pdfua.pdf');

下一步

• PDF/A-4 歸檔 — 歸檔合規的完整設定。
• PAdES 數位簽章 — 為無障礙文件加入數位簽章。
• 授權 — Pro 套件的商業授權條款。