Navigazione: annotazioni, link, struttura, azioni e allegati

In sintesi

Il modulo Navigation costruisce il livello interattivo del PDF: annotazioni, annotazioni di link e URL, struttura del documento (bookmark) e indice, azioni e catene di trigger, transizioni di pagina e allegati di file incorporati con le relative relazioni di file associato.

Installazione

composer require nextpdf/core:^3

Panoramica concettuale

ISO 32000-2 §12 definisce le funzionalità interattive di un PDF: annotazioni, azioni, destinazioni e struttura del documento. Questo modulo è il componente di encoding del motore per quel livello. È organizzato come un insieme di classi manager che accumulano l’intento e un insieme di value object emessi dai manager.

AnnotationManager è la superficie più ampia. Aggiunge annotazioni di testo, testo libero, linea, quadrato, cerchio, poligono, polilinea, inchiostro e marcatura del testo (evidenziazione, sottolineatura). È progettato in modo robusto: un sottotipo di annotazione sconosciuto viene ricondotto a un valore predefinito sicuro, un nome di icona che non è un token di nome PDF valido viene sostituito e i QuadPoints di marcatura del testo devono essere forniti come multiplo di otto float, altrimenti vengono scartati. Si tratta di difese contro l’iniezione nel PDF, non di semplici comodità di validazione. LinkManager gestisce link interni, destinazioni con nome e annotazioni di URL. Prealloca gli oggetti di annotazione affinché il Writer possa farvi riferimento prima della serializzazione.

BookmarkManager e TocBuilder costruiscono la gerarchia di navigazione. La struttura del documento è l’albero di bookmark che un visualizzatore mostra nella propria barra laterale; TocBuilder esegue il rendering di un indice nella pagina e può usare FontMetrics per il layout leader/width. OutlineAutoGenerator deriva una struttura dalla struttura del documento.

La gerarchia Action sotto NextPDF\Navigation\Action modella il comportamento guidato dai trigger: GoTo (remoto e incorporato), launch, named, hide, form reset/submit e impostazione dello stato del contenuto opzionale. L’azione di rendition per le annotazioni schermo del §13 è rinviata: rientra nel lavoro futuro e non è ancora collegata, quindi non va considerata un’azione supportata. Action::withNext() costruisce la catena di azioni eseguita da un singolo evento trigger. PageTransition modella una transizione di presentazione. FileAttachment incorpora un file da un percorso o da una stringa di byte e lo etichetta con un AFRelationship (l’enum della relazione di file associato). Restituisce un FileAttachmentResult e scrive tramite writeAttachments(). I manager principali sono @since 1.0.0. La gerarchia delle azioni è @since 2.1.0. Il costruttore di FileAttachment e AFRelationship sono stati introdotti con @since 1.8.0 / @since 1.1.0.

Superficie API

Classe	Membri chiave	Ruolo
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	Builder di annotazioni con input sicuri contro l’iniezione (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	Link interni, destinazioni con nome, annotazioni di URL (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	Albero della struttura del documento (bookmark) (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	Indice nella pagina (@since 1.0.0)
Action (interfaccia)	subtype(), toDictionary(), withNext(), nextChain()	Azione trigger + catena di azioni (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	Transizione di pagina per presentazioni (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	Allegati di file incorporati (@since 1.0.0)
AFRelationship (enum)	toPdfName()	Relazione di file associato (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	Insieme di flag di annotazione immutabile (@since 1.2.0)

Eseguire composer docs:generate-api-php -- --module=Navigation per la tabella PHPDoc completa.

Esempio di codice — Avvio rapido

Sorgente: examples/12-bookmarks-and-toc.php costruisce la struttura del documento tramite la facade di alto livello che incapsula BookmarkManager. Quando si lavora direttamente con il manager:

<?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.
}

Esempio di codice — Produzione

Incorporare un allegato con una relazione di file associato esplicita e controllare il risultato prima che il documento venga finalizzato.

<?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);
}

Casi limite e insidie

• AnnotationManager normalizza silenziosamente l’input ostile: un sottotipo non valido diventa quello predefinito, un’icona che non è un nome diventa l’icona predefinita e i QuadPoints malformati vengono scartati. L’annotazione viene comunque prodotta: validare gli input a monte se devono essere applicati con esattezza.
• LinkManager::preallocateAnnotationObjects() deve essere eseguito prima che il Writer serializzi i riferimenti, altrimenti le destinazioni dei link non si risolvono in nulla.
• Action::withNext() restituisce una nuova azione con la catena collegata; l’interfaccia è costruita per il concatenamento immutabile, non per la mutazione sul posto.
• FileAttachment::writeAttachments() richiede un ObjectRegistry attivo dal Writer. Chiamare il manager in isolamento accumula l’intento ma non scrive nulla finché il Writer non lo guida.
• AnnotationFlags è un insieme di flag immutabile. with()/without() restituiscono una nuova istanza; l’originale rimane invariato.

Prestazioni

L’accumulo di annotazioni, link e bookmark è O(n) nel numero di elementi, senza reflow. Il costo dell’allegato di file incorporato è dominato dalla dimensione in byte del file incorporato, non dal manager. Il carico di lavoro di riferimento predefinito rientra nel budget di 1500 ms di wall / 64 MB di picco. Il profilo di riproducibilità è structural: i numeri di oggetto e il /ID del trailer differiscono tra le esecuzioni. Due documenti con lo stesso intento di navigazione sono strutturalmente uguali ma non identici a livello di byte.

Note di sicurezza

AnnotationManager tratta il sottotipo di annotazione, l’icona e i QuadPoints come non attendibili: ciascuno viene validato rispetto a un elenco di valori consentiti o a un pattern e un valore errato viene sostituito anziché scritto. Questo chiude un vettore di iniezione di nome PDF. LinkManager::addUrlAnnotation() codifica un URL in un’azione di link. La valutazione di attendibilità dell’URL è responsabilità del consumatore: un URL ostile è un URL valido, quindi sanificare le destinazioni prima di aggiungerle. FileAttachment incorpora byte arbitrari. Limitare la dimensione del file incorporato e trattare la sorgente dell’allegato come non attendibile quando proviene da un utente. Consultare il modello di minaccia del motore in /modules/core/security/.

Conformità

Le strutture emesse da questo modulo seguono ISO 32000-2 §12 — annotazioni, azioni, destinazioni — e la gerarchia della struttura del documento. I riferimenti di clausola per funzionalità (icone di annotazione §12.5.6.4, QuadPoints di marcatura del testo §12.5.6.10, azioni §12.6) sono documentati inline in src/Navigation/ ed esercitati da tests/Unit/Navigation/. Si tratta di fatti di implementazione, non di una dichiarazione di conformità PDF 2.0 end-to-end. La conformità dell’intero documento è validata dall’oracle e dalle suite golden descritte in /modules/core/conformance/.

Vedi anche

• Modulo Document
• Modulo Multimedia — gli oggetti rendition che un’azione di rendition riproduce.
• Modulo Writer — serializza le strutture di navigazione.
• Panoramica sulla conformità
• Modello di sicurezza del motore