Navigatie: annotaties, koppelingen, bladwijzers, acties en bijlagen

In het kort

De Navigation-module bouwt de interactieve laag van het Portable Document Format (PDF). De module behandelt annotaties, koppelingen en Uniform Resource Locator (URL)-annotaties, de document outline (bladwijzers), de inhoudsopgave, acties en triggerketens, paginaovergangen en bijlagen van ingesloten bestanden met de bijbehorende associated-file-relaties.

Installatie

composer require nextpdf/core:^3

Conceptueel overzicht

ISO 32000-2 §12 definieert de interactieve functies van een PDF-document: annotaties, acties, bestemmingen en de document outline. Deze module encodeert die laag voor de engine. Managerklassen verzamelen de intentie; value objects bevatten de gegevens die de managers uitsturen.

AnnotationManager is het breedste toegangspunt. De manager voegt annotaties toe van het type tekst, vrije tekst, lijn, rechthoek, cirkel, veelhoek, gebroken lijn, inkt en tekstopmaak (markeren en onderstrepen). De manager is gehard tegen vijandige invoer: een onbekend annotatiesubtype wordt teruggezet naar een veilige standaard, een pictogramnaam die geen geldig PDF-name-token is, wordt vervangen, en QuadPoints voor tekstopmaak moeten worden aangeleverd als een veelvoud van acht floats, anders worden ze verworpen. Deze controles zijn bedoeld als verdediging tegen PDF-injectie, niet als handige validatievoorzieningen. LinkManager verwerkt interne koppelingen, benoemde bestemmingen en URL-annotaties. De manager reserveert annotatieobjecten vooraf, zodat de Writer ernaar kan verwijzen voordat de serialisatie plaatsvindt.

BookmarkManager en TocBuilder bouwen de navigatiehiërarchie op. De document outline is de bladwijzerstructuur die een viewer in de zijbalk toont. TocBuilder geeft een inhoudsopgave op de pagina weer en kan FontMetrics gebruiken voor de leader/width-lay-out. OutlineAutoGenerator leidt een outline af uit de documentstructuur.

De Action-hiërarchie onder NextPDF\Navigation\Action modelleert gedrag dat door triggers wordt aangestuurd: GoTo (extern en ingesloten), launch, named, hide, reset/submit form en het instellen van de optional-content-status. De §13 rendition-actie voor schermannotaties is uitgesteld; dit is toekomstig werk en is nog niet aangesloten. Vertrouw er niet op als een ondersteunde actie. Action::withNext() bouwt de actieketen die voor één triggergebeurtenis wordt uitgevoerd. PageTransition modelleert een presentatieovergang. FileAttachment sluit een bestand in vanuit een pad of een bytestring en voorziet het van een AFRelationship (de enum voor de associated-file-relatie). De methode retourneert een FileAttachmentResult en schrijft via writeAttachments(). De kernmanagers zijn @since 1.0.0. De actiehiërarchie is @since 2.1.0. De FileAttachment-constructor en AFRelationship kwamen beschikbaar in @since 1.8.0 / @since 1.1.0.

API-oppervlak

Klasse	Belangrijkste leden	Rol
`AnnotationManager`	`addAnnotation()`, `addFreeText()`, `addLine()`, `addSquare()`, `addCircle()`, `addPolygon()`, `addInk()`, `addHighlight()`, `addUnderline()`	Annotatiebouwer met invoer die veilig is tegen injectie (`@since 1.0.0`)
`LinkManager`	`addLink()`, `setLink()`, `setDestination()`, `addLinkAnnotation()`, `addUrlAnnotation()`, `preallocateAnnotationObjects()`	Interne koppelingen, benoemde bestemmingen, URL-annotaties (`@since 1.0.0`)
`BookmarkManager`	`addBookmark()`, `hasBookmarks()`, `write()`	Document outline-structuur (bladwijzers) (`@since 1.0.0`)
`TocBuilder`	`addEntry()`, `hasEntries()`, `render()`, `getEntries()`	Inhoudsopgave op de pagina (`@since 1.0.0`)
`Action` (interface)	`subtype()`, `toDictionary()`, `withNext()`, `nextChain()`	Triggeractie + actieketen (`@since 2.1.0`)
`PageTransition`	`toDict()`, `toInlineDict()`	Paginaovergang voor presentaties (`@since 1.2.0`)
`FileAttachment`	`embedFile()`, `embedFileFromString()`, `hasAttachments()`, `getCount()`, `writeAttachments()`	Bijlagen van ingesloten bestanden (`@since 1.0.0`)
`AFRelationship` (enum)	`toPdfName()`	Associated-file-relatie (`@since 1.1.0`)
`AnnotationFlags`	`with()`, `without()`, `has()`, `toInt()`	Onveranderlijke set annotatievlaggen (`@since 1.2.0`)

Voer composer docs:generate-api-php -- --module=Navigation uit om de volledige PHPDoc-tabel te genereren.

Codevoorbeeld — Snelstart

examples/12-bookmarks-and-toc.php bouwt de document outline op via de high-level facade die BookmarkManager omhult. Als je de manager rechtstreeks wilt gebruiken:

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

Codevoorbeeld — Productie

Sluit een bijlage in met een expliciete associated-file-relatie en controleer daarna het resultaat voordat je het document voltooit.

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

Randgevallen en valkuilen

AnnotationManager normaliseert vijandige invoer stilzwijgend: een ongeldig subtype wordt teruggezet naar de standaard, een pictogram dat geen name is, wordt het standaardpictogram, en misvormde QuadPoints worden verworpen. De annotatie wordt nog steeds geproduceerd; valideer de invoer stroomopwaarts als die exact moet worden gerespecteerd.
LinkManager::preallocateAnnotationObjects() moet worden uitgevoerd voordat de Writer verwijzingen serialiseert, anders verwijzen koppelingsdoelen naar niets.
Action::withNext() retourneert een nieuwe actie met de keten eraan gekoppeld; de interface ondersteunt onveranderlijke koppeling, geen mutatie ter plaatse.
FileAttachment::writeAttachments() vereist een actieve ObjectRegistry van de Writer. Wanneer de manager los wordt aangeroepen, verzamelt hij de intentie maar schrijft hij niets totdat de Writer hem aanstuurt.
AnnotationFlags is een onveranderlijke set vlaggen. with()/without() retourneren een nieuwe instantie; het origineel blijft ongewijzigd.

Prestaties

Het opbouwen van annotaties, koppelingen en bladwijzers is O(n) in het aantal items en voert geen reflow uit. De kosten van een bijlage met een ingesloten bestand worden bepaald door de ingesloten bytegrootte, niet door de overhead van de manager. De standaardreferentiebelasting blijft binnen het budget van 1500 ms wandkloktijd / 64 MB piekgeheugen. Het reproduceerbaarheidsprofiel is structural: objectnummers en de trailer-/ID verschillen tussen uitvoeringen. Twee documenten met dezelfde navigatie-intentie zijn structureel gelijk, maar niet byte-identiek.

Opmerkingen over beveiliging

AnnotationManager behandelt het annotatiesubtype, het pictogram en QuadPoints als niet-vertrouwd. De manager valideert elke waarde aan de hand van een allow-list of patroon en vervangt een ongeldige waarde in plaats van deze door te schrijven. Hiermee wordt een PDF-name-injectievector gesloten. LinkManager::addUrlAnnotation() codeert een URL in een koppelingsactie. De URL blijft de vertrouwensgrens voor de consument: een vijandige URL kan nog steeds geldig zijn, dus saneer bestemmingen voordat je ze toevoegt. FileAttachment sluit willekeurige bytes in. Begrens de ingesloten grootte en behandel elke door de gebruiker aangeleverde bijlagebron als niet-vertrouwd. Zie het dreigingsmodel van de engine in /modules/core/security/.

Conformiteit

De structuren die deze module uitstuurt, volgen ISO 32000-2 §12 voor annotaties, acties, bestemmingen en de document-outline-hiërarchie. Clausuleverwijzingen per functie (annotatiepictogrammen §12.5.6.4, tekstopmaak-QuadPoints §12.5.6.10, acties §12.6) zijn inline gedocumenteerd in src/Navigation/ en worden getest door tests/Unit/Navigation/. Dit zijn implementatiefeiten, geen verklaring van end-to-end PDF 2.0-conformiteit. Conformiteit op documentniveau wordt gevalideerd door de oracle- en golden-suites die worden beschreven in /modules/core/conformance/.

Zie ook

Document-module
Multimedia-module — de rendition-objecten die een rendition-actie afspeelt.
Writer-module — serialiseert de navigatiestructuren.
Overzicht van conformiteit
Beveiligingsmodel van de engine