Navegación: anotaciones, enlaces, esquemas, acciones y archivos adjuntos

De un vistazo

El módulo Navigation construye la capa interactiva del PDF: anotaciones, anotaciones de enlace y URL, el esquema del documento (marcadores) y la tabla de contenidos, acciones y cadenas de disparadores, transiciones de página y archivos adjuntos incrustados con sus relaciones de archivo asociado.

Instalación

composer require nextpdf/core:^3

Resumen conceptual

ISO 32000-2 §12 define las características interactivas de un PDF: anotaciones, acciones, destinos y el esquema del documento. Este módulo codifica esa capa dentro del motor. Se organiza en clases gestoras que acumulan la intención y en objetos de valor emitidos por esas gestoras.

AnnotationManager es la superficie más amplia. Permite añadir anotaciones de texto, texto libre, línea, cuadrado, círculo, polígono, polilínea, tinta y marcado de texto (resaltado, subrayado). Está reforzado: un subtipo de anotación desconocido se sustituye por un valor predeterminado seguro, un nombre de icono que no es un token de nombre PDF válido se reemplaza, y los QuadPoints de marcado de texto deben recibirse como un múltiplo de ocho floats o se descartan. Son defensas contra inyección de PDF, no simples facilidades de validación. LinkManager gestiona enlaces internos, destinos con nombre y anotaciones de URL. Preasigna los objetos de anotación para que el Writer pueda referenciarlos antes de serializarlos.

BookmarkManager y TocBuilder construyen la jerarquía de navegación. El esquema del documento es el árbol de marcadores que un visor muestra en su barra lateral; TocBuilder representa una tabla de contenidos en la página y puede usar FontMetrics para el diseño de leader/width. OutlineAutoGenerator deriva un esquema desde la estructura del documento.

La jerarquía Action bajo NextPDF\Navigation\Action modela el comportamiento impulsado por disparadores: GoTo (remoto e incrustado), launch, named, hide, reset/submit de formulario y establecimiento del estado de contenido opcional. La acción de representación de la anotación de pantalla de §13 está pospuesta: es trabajo futuro y aún no está conectada, así que no se debe confiar en ella como una acción admitida. Action::withNext() construye la cadena de acciones que ejecuta un único evento disparador. PageTransition modela una transición de presentación. FileAttachment incrusta un archivo a partir de una ruta o una cadena de bytes y lo etiqueta con un AFRelationship (el enum de relación de archivo asociado). Devuelve un FileAttachmentResult y escribe mediante writeAttachments(). Las gestoras del núcleo son @since 1.0.0. La jerarquía de acciones es @since 2.1.0. El constructor de FileAttachment y AFRelationship se incorporaron en @since 1.8.0 / @since 1.1.0.

Superficie de la API

Clase	Miembros clave	Función
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	Constructor de anotaciones con entradas protegidas contra inyección (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	Enlaces internos, destinos con nombre, anotaciones de URL (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	Árbol del esquema del documento (marcadores) (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	Tabla de contenidos en la página (@since 1.0.0)
Action (interfaz)	subtype(), toDictionary(), withNext(), nextChain()	Acción activada por disparador + cadena de acciones (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	Transición de página de presentación (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	Archivos adjuntos incrustados (@since 1.0.0)
AFRelationship (enum)	toPdfName()	Relación de archivo asociado (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	Conjunto inmutable de banderas de anotación (@since 1.2.0)

Ejecutar composer docs:generate-api-php -- --module=Navigation para obtener la tabla PHPDoc completa.

Ejemplo de código — Inicio rápido

Fuente: examples/12-bookmarks-and-toc.php construye el esquema del documento mediante la fachada de alto nivel que envuelve a BookmarkManager. Al trabajar directamente con la gestora:

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Navigation\BookmarkManager;

$bookmarks = new BookmarkManager();
$bookmarks->addBookmark(title: 'Chapter 1', level: 0, pageIndex: 0);
$bookmarks->addBookmark(title: '1.1 Overview', level: 1, pageIndex: 0);
$bookmarks->addBookmark(title: 'Chapter 2', level: 0, pageIndex: 4);

if ($bookmarks->hasBookmarks()) {
    // The Writer calls $bookmarks->write(...) during catalog serialization.
}

Ejemplo de código — Producción

Incrustar un archivo adjunto con una relación de archivo asociado explícita y comprobar el resultado antes de finalizar el documento.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Navigation\AFRelationship;
use NextPDF\Navigation\FileAttachment;

$attachments = new FileAttachment();

$attachments->embedFile(
    path: '/srv/invoices/INV-2026-0042.xml',
    description: 'Structured invoice source (Factur-X)',
    afRelationship: AFRelationship::Source,
);

if ($attachments->hasAttachments()) {
    // writeAttachments() is invoked by the Writer with a live ObjectRegistry;
    // getCount() lets the application assert the expected attachment count.
    assert($attachments->getCount() === 1);
}

Casos límite y trampas

• AnnotationManager normaliza silenciosamente las entradas hostiles: un subtipo no válido se convierte en el predeterminado, un icono que no es un nombre se convierte en el icono predeterminado, y los QuadPoints malformados se descartan. La anotación se genera de todos modos; verificar las entradas en origen si deben respetarse exactamente.
• LinkManager::preallocateAnnotationObjects() debe ejecutarse antes de que el Writer serialice las referencias; de lo contrario, los destinos de los enlaces no se resolverán en ningún destino.
• Action::withNext() devuelve una nueva acción con la cadena adjunta; la interfaz está diseñada para el encadenamiento inmutable, no para la mutación in situ.
• FileAttachment::writeAttachments() requiere un ObjectRegistry activo del Writer. Llamar a la gestora de forma aislada acumula la intención, pero no escribe nada hasta que el Writer la impulsa.
• AnnotationFlags es un conjunto inmutable de banderas. with()/without() devuelven una nueva instancia; la original no se modifica.

Rendimiento

La acumulación de anotaciones, enlaces y marcadores es O(n) en el número de elementos, sin reflujo. El coste de los archivos adjuntos incrustados está dominado por el tamaño en bytes incrustado, no por la gestora. La carga de trabajo de referencia predeterminada queda dentro del presupuesto de 1500 ms de tiempo de reloj / 64 MB de pico. El perfil de reproducibilidad es structural: los números de objetos y el /ID del tráiler difieren entre ejecuciones. Dos documentos con la misma intención de navegación son estructuralmente iguales, pero no idénticos byte a byte.

Notas de seguridad

AnnotationManager trata el subtipo de anotación, el icono y los QuadPoints como no confiables: cada uno se valida contra una lista de permitidos o un patrón, y un valor incorrecto se reemplaza en lugar de escribirse directamente. Con ello se cierra un vector de inyección de nombres PDF. LinkManager::addUrlAnnotation() codifica una URL en una acción de enlace. La confianza en la URL es responsabilidad del consumidor: una URL hostil es una URL válida, así que sanear los destinos antes de añadirlos. FileAttachment incrusta bytes arbitrarios. Acotar el tamaño incrustado y tratar el origen del archivo adjunto como no confiable cuando provenga de un usuario. Consultar el modelo de amenazas del motor en /modules/core/security/.

Conformidad

Las estructuras que este módulo emite siguen ISO 32000-2 §12 — anotaciones, acciones, destinos — y la jerarquía del esquema del documento. Las referencias de cláusula por característica (iconos de anotación §12.5.6.4, QuadPoints de marcado de texto §12.5.6.10, acciones §12.6) están documentadas en línea en src/Navigation/ y se ejercitan mediante tests/Unit/Navigation/. Son hechos de implementación, no una declaración de conformidad PDF 2.0 de extremo a extremo. La conformidad del documento completo la valida el oráculo y las suites golden descritas en /modules/core/conformance/.

Véase también

• Módulo Document
• Módulo Multimedia — los objetos de representación que reproduce una acción de representación.
• Módulo Writer — serializa las estructuras de navegación.
• Resumen de conformidad
• Modelo de seguridad del motor