Tagged PDF (Trợ năng)

Module Accessibility (StructureTreeManager, RoleMap, TaggedContentManager) cho phép xuất tagged PDF cho trình đọc màn hình và công nghệ trợ năng. Khi bật, mọi phần nội dung được bọc trong structure element mô tả vai trò ngữ nghĩa. Mọi method tagging trả về static để chain.

Tham chiếu nhanh

Method	Mô tả
setTaggedPdf()	Bật hoặc tắt chế độ tagged PDF
setLanguage()	Đặt ngôn ngữ chính của document (BCP 47)
openTag()	Bắt đầu tagged structure element
closeTag()	Kết thúc tagged structure element
image(..., alt:)	Thêm hình ảnh với alt text cho trợ năng

Bật Tagged PDF

use Yeeefang\TcpdfNext\Core\Document;

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

Khi gọi setTaggedPdf(true), StructureTreeManager được khởi tạo lazy và dictionary MarkInfo với Marked = true được ghi vào PDF catalog.

Structure Element

TCPDF-Next hỗ trợ đầy đủ tập tag chuẩn PDF 2.0:

Danh mục	Tag
Nhóm	Document, Part, Sect, Div, BlockQuote, Caption, NonStruct
Tiêu đề	H1, H2, H3, H4, H5, H6
Đoạn văn	P, Span
Danh sách	L, LI, Lbl, LBody
Bảng	Table, TR, TH, TD, THead, TBody, TFoot
Inline	Link, Em, Strong, Code
Minh họa	Figure, Formula, Form

Tagging cơ bản

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setLanguage('en-US')
    ->addPage()
    ->setFont('Helvetica', '', 12)

    ->openTag('H1')
    ->cell(0, 10, 'Annual Report 2026', newLine: true)
    ->closeTag('H1')

    ->openTag('P')
    ->multiCell(0, 6, 'This document demonstrates tagged PDF output for accessibility compliance.')
    ->closeTag('P')

    ->save('tagged-basic.pdf');

Tag phải được lồng đúng. StructureTreeManager kiểm tra lồng nhau và throw exception khi không khớp.

Bảng Tagged

$pdf->openTag('Table')
    ->openTag('TR')
    ->openTag('TH')->cell(50, 8, 'Quarter')->closeTag('TH')
    ->openTag('TH')->cell(50, 8, 'Revenue')->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');

Thuộc tính Tag

Truyền thuộc tính bổ sung khi mở tag:

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

Thuộc tính phổ biến:

Thuộc tính	Mô tả
Alt	Text thay thế cho phần tử phi text
ActualText	Text thay thế chính xác cho phần tử
Lang	Ghi đè ngôn ngữ cho phần tử này (BCP 47)
Title	Tiêu đề dễ đọc

Method image() cũng nhận tham số alt dạng viết tắt — $pdf->image('chart.png', 10, 80, 120, 60, alt: 'Revenue chart') tự động bọc hình ảnh trong tag Figure.

Role Mapping

RoleMap ánh xạ tên tag tùy chỉnh sang kiểu structure PDF chuẩn. Cho phép bạn dùng tên theo lĩnh vực chuyên môn mà vẫn tương thích 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');

Role map được ghi vào gốc structure tree để validator phân giải tag tùy chỉnh sang tương đương chuẩn. Cho nội dung đa ngôn ngữ, ghi đè ngôn ngữ theo phần tử: ->openTag('P', ['Lang' => 'de-DE']).

Tuân thủ PDF/UA

Để tạo document tuân thủ PDF/UA đầy đủ, đảm bảo:

1. Tagged PDF đã bật — setTaggedPdf(true)
2. Ngôn ngữ document đã đặt — setLanguage('en-US')
3. Mọi nội dung đều tagged — không có nội dung untagged ngoài structure element
4. Mọi hình ảnh có alt text — qua tham số alt: hoặc tag Figure với thuộc tính Alt
5. Bảng dùng TH cho header — ô header phải phân biệt với ô dữ liệu
6. Font được nhúng — TCPDF-Next nhúng mọi font theo mặc định

Tích hợp với PDF/A-4

Tagged PDF tương thích hoàn toàn với PDF/A-4. Bật cả hai cho document lưu trữ + trợ năng:

$pdf = Document::create()
    ->setTaggedPdf(true)
    ->setPdfA(true)
    ->setLanguage('en-US')
    ->setTitle('Accessible Archival Document')
    ->addPage()
    ->setFont('Helvetica', '', 12)
    ->openTag('H1')
    ->cell(0, 10, 'PDF/A-4 + PDF/UA Document', newLine: true)
    ->closeTag('H1')
    ->save('accessible-archival.pdf');