PDF etiquetado (Accesibilidad)

El módulo de Accesibilidad (StructureTreeManager, RoleMap, TaggedContentManager) habilita la salida PDF etiquetada para lectores de pantalla y tecnologías de asistencia. Cuando se habilita, cada pieza de contenido se envuelve en elementos de estructura que describen su rol semántico. Todos los métodos de etiquetado retornan static para encadenamiento.

Referencia rápida

Método	Descripción
setTaggedPdf()	Habilitar o deshabilitar el modo PDF etiquetado
setLanguage()	Establecer el idioma principal del documento (BCP 47)
openTag()	Iniciar un elemento de estructura etiquetado
closeTag()	Finalizar un elemento de estructura etiquetado
image(..., alt:)	Agregar una imagen con texto alternativo para accesibilidad

Habilitar PDF etiquetado

use Yeeefang\TcpdfNext\Core\Document;

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

Cuando se llama setTaggedPdf(true), el StructureTreeManager se inicializa de forma perezosa y un diccionario MarkInfo con Marked = true se escribe en el catálogo PDF.

Elementos de estructura

TCPDF-Next soporta el conjunto completo de etiquetas estándar PDF 2.0:

Categoría	Etiquetas
Agrupación	Document, Part, Sect, Div, BlockQuote, Caption, NonStruct
Encabezados	H1, H2, H3, H4, H5, H6
Párrafos	P, Span
Listas	L, LI, Lbl, LBody
Tablas	Table, TR, TH, TD, THead, TBody, TFoot
En línea	Link, Em, Strong, Code
Ilustraciones	Figure, Formula, Form

Etiquetado básico

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

Las etiquetas deben estar correctamente anidadas. El StructureTreeManager valida la anidación y lanza una excepción en caso de desajuste.

Tablas etiquetadas

$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 etiqueta

Pasa atributos adicionales al abrir una etiqueta:

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

Atributos comunes:

Atributo	Descripción
Alt	Texto alternativo para elementos no textuales
ActualText	Reemplazo exacto de texto para el elemento
Lang	Sobrescritura de idioma para este elemento (BCP 47)
Title	Título legible por humanos

El método image() también acepta un parámetro alt como atajo — $pdf->image('chart.png', 10, 80, 120, 60, alt: 'Revenue chart') envuelve automáticamente la imagen en una etiqueta Figure.

Mapeo de roles

El RoleMap mapea nombres de etiquetas personalizados a tipos de estructura PDF estándar. Esto te permite usar nombres específicos del dominio mientras mantienes la compatibilidad 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');

El mapa de roles se escribe en la raíz del árbol de estructura para que los validadores resuelvan las etiquetas personalizadas a equivalentes estándar. Para contenido multilingüe, sobrescribe el idioma por elemento: ->openTag('P', ['Lang' => 'de-DE']).

Cumplimiento PDF/UA

Para producir un documento completamente compatible con PDF/UA, asegúrate de:

1. PDF etiquetado habilitado — setTaggedPdf(true)
2. Idioma del documento establecido — setLanguage('en-US')
3. Todo el contenido etiquetado — sin contenido no etiquetado fuera de los elementos de estructura
4. Todas las imágenes con texto alternativo — a través del parámetro alt: o etiqueta Figure con atributo Alt
5. Tablas con TH para encabezados — las celdas de encabezado deben distinguirse de las celdas de datos
6. Fuentes incrustadas — TCPDF-Next incrusta todas las fuentes por defecto

Integración con PDF/A-4

El PDF etiquetado es completamente compatible con PDF/A-4. Habilita ambos para documentos archivables + accesibles:

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