跳轉到

Tagged PDF（結構化 PDF）

Tagged PDF 在 PDF 文件中加入語義標籤結構（Structure Tree），讓螢幕閱讀器、點字顯示器等輔助技術能理解文件內容的邏輯順序與意義。這是 PDF/UA-1、PDF/UA-2 合規以及 WCAG 無障礙標準的基礎要求。

啟用 Tagged PDF

use NextPDF\Core\Configuration;

$config = Configuration::create(
    taggedPdf: true,               // 啟用 Tagged PDF 基礎設施
    documentLanguage: 'zh-TW',    // 設定文件主要語言
    title: 'Accessible Document', // Tagged PDF 要求標題非空
);

StructureTree 與 StructureElement

use NextPDF\Accessibility\StructureTree;
use NextPDF\Accessibility\StructureElement;
use NextPDF\Accessibility\StructureType;

$structTree = $document->structureTree();

// 建立文件結構
$documentElem = $structTree->root()
    ->addChild(StructureType::Document);

$section1 = $documentElem
    ->addChild(StructureType::Section);

$heading1 = $section1
    ->addChild(StructureType::H1)
    ->setAlternateText('Chapter 1: Introduction');

$paragraph = $section1
    ->addChild(StructureType::P);

標準結構類型

use NextPDF\Accessibility\StructureType;

// 文件層級
StructureType::Document   // 完整文件
StructureType::Part       // 大型文件區塊
StructureType::Section    // 章節

// 段落層級
StructureType::P          // 段落
StructureType::H          // 一般標題
StructureType::H1         // 第一層標題
StructureType::H2         // 第二層標題
StructureType::H6         // 第六層標題

// 行內元素
StructureType::Span       // 行內文字範圍
StructureType::Quote      // 引用
StructureType::Code       // 程式碼

// 清單
StructureType::L          // 清單
StructureType::LI         // 清單項目
StructureType::Lbl        // 清單標籤
StructureType::LBody      // 清單內容

// 表格
StructureType::Table      // 表格
StructureType::TR         // 表格列
StructureType::TH         // 表頭儲存格
StructureType::TD         // 資料儲存格

// 圖形
StructureType::Figure     // 圖形（需要 Alt 文字）
StructureType::Caption    // 說明文字

// 特殊
StructureType::Artifact   // 裝飾性內容（頁首、頁尾、浮水印）

標記內容（Marked Content）

// 在渲染時關聯結構元素
$headingElem = $section1->addChild(StructureType::H1);

$document->text()->write(
    text: 'Chapter 1: Introduction',
    position: Position::at(x: 20.0, y: 250.0),
    style: FontStyle::create(fontSize: 18.0, bold: true),
    structureElement: $headingElem,  // 關聯結構元素
);

圖片無障礙

use NextPDF\Accessibility\StructureType;

$figureElem = $section1->addChild(StructureType::Figure);
$figureElem->setAlternateText('Company logo: Acme Corp in blue');
$figureElem->setActualText('ACME CORP');  // 可選：圖片的實際文字內容

$document->images()->place(
    path: '/path/to/logo.png',
    position: Rectangle::fromXY(x: 20.0, y: 250.0, width: 50.0, height: 20.0),
    structureElement: $figureElem,
);

RoleMap 自訂結構類型

use NextPDF\Accessibility\RoleMap;

// 將自訂標籤映射至標準結構類型
$document->structureTree()->roleMap()->add(
    customType: 'Invoice',
    standardType: StructureType::Section,
);

$document->structureTree()->roleMap()->add(
    customType: 'InvoiceItem',
    standardType: StructureType::P,
);

閱讀順序

Tagged PDF 的閱讀順序由 StructureTree 決定，應與視覺呈現一致：

// 多欄版面中指定正確的閱讀順序
$section->addChild(StructureType::P)->setReadingOrder(1); // 第一欄第一段
$section->addChild(StructureType::P)->setReadingOrder(2); // 第一欄第二段
$section->addChild(StructureType::P)->setReadingOrder(3); // 第二欄第一段

參見