PDF com Tags (Acessibilidade)

O módulo Accessibility (StructureTreeManager, RoleMap, TaggedContentManager) habilita saída de PDF com tags para leitores de tela e tecnologias assistivas. Quando habilitado, cada pedaço de conteúdo é envolvido em elementos de estrutura que descrevem seu papel semântico. Todos os métodos de tags retornam static para encadeamento.

Referência Rápida

Método	Descrição
setTaggedPdf()	Habilitar ou desabilitar modo PDF com tags
setLanguage()	Definir o idioma principal do documento (BCP 47)
openTag()	Iniciar um elemento de estrutura com tag
closeTag()	Encerrar um elemento de estrutura com tag
image(..., alt:)	Adicionar imagem com texto alt para acessibilidade

Habilitando PDF com Tags

use Yeeefang\TcpdfNext\Core\Document;

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

Quando setTaggedPdf(true) é chamado, o StructureTreeManager é inicializado de forma lazy e um dicionário MarkInfo com Marked = true é escrito no catálogo PDF.

Elementos de Estrutura

O TCPDF-Next suporta o conjunto completo de tags do padrão PDF 2.0:

Categoria	Tags
Agrupamento	Document, Part, Sect, Div, BlockQuote, Caption, NonStruct
Cabeçalhos	H1, H2, H3, H4, H5, H6
Parágrafos	P, Span
Listas	L, LI, Lbl, LBody
Tabelas	Table, TR, TH, TD, THead, TBody, TFoot
Inline	Link, Em, Strong, Code
Ilustrações	Figure, Formula, Form

Tags Básicas

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

As tags devem ser devidamente aninhadas. O StructureTreeManager valida o aninhamento e lança uma exceção em caso de incompatibilidade.

Tabelas com Tags

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

Atributos de Tag

Passe atributos adicionais ao abrir uma tag:

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

Atributos comuns:

Atributo	Descrição
Alt	Texto alternativo para elementos não textuais
ActualText	Substituição de texto exata para o elemento
Lang	Substituição de idioma para este elemento (BCP 47)
Title	Título legível para humanos

O método image() também aceita um parâmetro alt como atalho — $pdf->image('chart.png', 10, 80, 120, 60, alt: 'Revenue chart') automaticamente envolve a imagem em uma tag Figure.

Mapeamento de Papéis

O RoleMap mapeia nomes de tags personalizados para tipos de estrutura PDF padrão. Isso permite usar nomes específicos do domínio mantendo compatibilidade com 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');

O mapeamento de papéis é escrito na raiz da árvore de estrutura para que validadores resolvam tags personalizadas para equivalentes padrão. Para conteúdo multilíngue, substitua o idioma por elemento: ->openTag('P', ['Lang' => 'de-DE']).

Conformidade PDF/UA

Para produzir um documento totalmente conforme com PDF/UA, garanta:

1. PDF com tags habilitado — setTaggedPdf(true)
2. Idioma do documento definido — setLanguage('en-US')
3. Todo conteúdo com tags — sem conteúdo sem tag fora dos elementos de estrutura
4. Todas as imagens com texto alt — via parâmetro alt: ou tag Figure com atributo Alt
5. Tabelas usam TH para cabeçalhos — células de cabeçalho devem ser distinguidas das células de dados
6. Fontes incorporadas — o TCPDF-Next incorpora todas as fontes por padrão

Integração com PDF/A-4

PDF com tags é totalmente compatível com PDF/A-4. Habilite ambos para documentos arquivísticos + acessíveis:

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