Tagged PDF (Доступность)

Модуль Accessibility (StructureTreeManager, RoleMap, TaggedContentManager) включает тегированный PDF-вывод для экранных читалок и вспомогательных технологий. При включении каждый элемент контента оборачивается в структурные элементы, описывающие его семантическую роль. Все методы тегирования возвращают static для цепочки вызовов.

Краткий справочник

Метод	Описание
setTaggedPdf()	Включить или отключить режим Tagged PDF
setLanguage()	Установить основной язык документа (BCP 47)
openTag()	Начать тегированный структурный элемент
closeTag()	Завершить тегированный структурный элемент
image(..., alt:)	Добавить изображение с alt-текстом для доступности

Включение Tagged PDF

use Yeeefang\TcpdfNext\Core\Document;

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

При вызове setTaggedPdf(true) StructureTreeManager инициализируется лениво, и словарь MarkInfo с Marked = true записывается в каталог PDF.

Структурные элементы

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

Базовое тегирование

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');

Теги должны быть правильно вложены. StructureTreeManager проверяет вложенность и выбрасывает исключение при несоответствии.

Тегированные таблицы

$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');

Атрибуты тегов

Передавайте дополнительные атрибуты при открытии тега:

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

Общие атрибуты:

Атрибут	Описание
Alt	Альтернативный текст для нетекстовых элементов
ActualText	Точная текстовая замена для элемента
Lang	Переопределение языка для этого элемента (BCP 47)
Title	Человекочитаемый заголовок

Метод image() также принимает параметр alt как сокращение — $pdf->image('chart.png', 10, 80, 120, 60, alt: 'Revenue chart') автоматически оборачивает изображение в тег 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' => 'de-DE']).

Соответствие PDF/UA

Для создания документа, полностью соответствующего PDF/UA, обеспечьте:

1. Tagged PDF включён — setTaggedPdf(true)
2. Язык документа установлен — setLanguage('en-US')
3. Весь контент тегирован — нет нетегированного контента вне структурных элементов
4. Все изображения имеют alt-текст — через параметр alt: или тег Figure с атрибутом Alt
5. Таблицы используют TH для заголовков — ячейки заголовков должны быть отличены от ячеек данных
6. Шрифты встроены — TCPDF-Next встраивает все шрифты по умолчанию

Интеграция с PDF/A-4

Tagged PDF полностью совместим с PDF/A-4. Включите оба режима для архивных и доступных документов:

$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');