Navegación (HasNavigation)

El trait HasNavigation y sus módulos subyacentes (BookmarkManager, TocManager, AnnotationManager, FileAttachment) proporcionan funciones de navegación PDF: marcadores jerárquicos, tabla de contenidos auto-generada, enlaces internos y externos, destinos con nombre, anotaciones y archivos adjuntos incrustados. Todos los métodos retornan static, por lo que cada llamada puede ser encadenada.

Referencia rápida

Método	Funcionalidad
bookmark()	Agregar un marcador jerárquico / entrada de esquema
addTOC()	Auto-generar una tabla de contenidos con puntos guía
addHTMLTOC()	Tabla de contenidos con estilo HTML
addLink()	Crear un destino de enlace interno (retorna ID de enlace)
setLink()	Establecer posición de destino de enlace interno
setDestination()	Crear un ancla de destino con nombre
annotation()	Agregar una anotación de texto
addFileAttachment()	Incrustar un archivo adjunto en el PDF

Ejemplo básico

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)

    // Marcadores
    ->bookmark('Chapter 1', 0)
    ->cell(0, 10, 'Chapter 1: Introduction', newLine: true)
    ->bookmark('Section 1.1', 1)
    ->cell(0, 10, '1.1 Getting Started', newLine: true)

    // Enlace interno
    ->addPage()
    ->bookmark('Chapter 2', 0)
    ->cell(0, 10, 'Chapter 2: Advanced Topics', newLine: true)

    // Archivo adjunto
    ->addFileAttachment('/path/to/data.xlsx', 'data.xlsx', 'Supporting data')

    // Auto-generar TOC al final (insertar en página 1)
    ->addTOC(1, ' . ', 'Table of Contents');

Marcadores / Esquemas

$pdf->bookmark(string $txt, int $level = 0, float $y = -1, int $page = -1, string $style = '', array $color = []);

Los marcadores aparecen en el panel de esquema del lector PDF. Anídalos incrementando $level.

Tabla de contenidos

$pdf->addTOC(int $page, string $numberSuffix = '', string $bookmarkText = '');

Llama a addTOC() después de que todos los marcadores hayan sido agregados. La TOC se construye desde el árbol de marcadores y se inserta en la posición de página especificada. Usa addHTMLTOC() para control total sobre el estilo de las entradas a través de HTML y CSS.

Enlaces internos

Crea referencias cruzadas clicables entre páginas:

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12);

$linkId = $pdf->addLink();

$pdf->write(10, 'Jump to Chapter 2', link: $linkId)
    ->addPage()
    ->setLink($linkId, y: 0)
    ->cell(0, 10, 'Chapter 2 starts here', newLine: true);

Enlaces externos

Pasa una cadena URL como parámetro $link en cell(), write() o image():

$pdf->cell(0, 10, 'Visit our website', link: 'https://example.com', newLine: true)
    ->write(10, 'Click here', link: 'https://docs.example.com');

Destinos con nombre

$pdf->setDestination(string $name, float $y = -1, int $page = -1);

Los destinos con nombre permiten que documentos externos o URLs enlacen a una ubicación específica a través del fragmento #name.

Anotaciones

$pdf->annotation(float $x, float $y, float $w, float $h, string $text, array $opt = []);

Las anotaciones aparecen como iconos de nota adhesiva en el visor PDF.

$pdf->annotation(50, 80, 10, 10, 'Review this section before release.', [
    'subtype' => 'Text',
    'icon'    => 'Comment',
    'color'   => [255, 255, 0],
]);

Archivos adjuntos

$pdf->addFileAttachment(string $file, string $name, string $desc);

Los archivos incrustados aparecen en el panel de adjuntos del lector PDF.

$pdf->addFileAttachment('/reports/q4-data.xlsx', 'q4-data.xlsx', 'Q4 financial data')
    ->addFileAttachment('/reports/methodology.pdf', 'methodology.pdf', 'Research methodology');