Navigation: Annotationen, Links, Lesezeichen, Aktionen und Anhänge

Auf einen Blick

Das Navigationsmodul baut die interaktive Ebene des PDFs auf: Annotationen, Link- und URL-Annotationen, das Dokument-Outline (Lesezeichen) und das Inhaltsverzeichnis, Aktionen und Auslöserketten, Seitenübergänge sowie Dateianhänge mit ihren zugehörigen Dateibeziehungen.

Installation

composer require nextpdf/core:^3

Konzeptioneller Überblick

ISO 32000-2 §12 definiert die interaktiven Funktionen eines PDFs — Annotationen, Aktionen, Sprungziele, das Dokument-Outline. Dieses Modul ist die Encoder-Komponente der Engine für diese Ebene. Es ist in Manager-Klassen, die Absichten sammeln, und Value Objects organisiert, die von den Managern ausgegeben werden.

AnnotationManager deckt den größten Aufgabenbereich ab. Er fügt Text-, Freitext-, Linien-, Rechteck-, Kreis-, Polygon-, Polylinien-, Tinten- und Textmarkierungs-Annotationen hinzu (Hervorhebung, Unterstreichung). Er ist gehärtet: Ein unbekannter Annotations-Subtyp wird auf einen sicheren Standard zurückgeführt, ein Symbolname, der kein gültiges PDF-Name-Token ist, wird ersetzt, und Textmarkierungs-QuadPoints müssen in Vielfachen von acht Floats vorliegen, andernfalls werden sie verworfen. Das sind Schutzmaßnahmen gegen PDF-Injection, keine Lockerungen der Validierung. LinkManager verarbeitet interne Links, benannte Sprungziele und URL-Annotationen. Er reserviert Annotationsobjekte vorab, damit der Writer sie referenzieren kann, bevor sie serialisiert werden.

BookmarkManager und TocBuilder bauen die Navigationshierarchie auf. Das Dokument-Outline bildet den Lesezeichenbaum, den ein Viewer in seiner Seitenleiste anzeigt; TocBuilder rendert ein Inhaltsverzeichnis auf der Seite und kann FontMetrics für das leader/width-Layout verwenden. OutlineAutoGenerator leitet aus der Dokumentstruktur ein Outline ab.

Die Action-Hierarchie unter NextPDF\Navigation\Action modelliert auslöserabhängiges Verhalten: GoTo (remote und eingebettet), Launch, Named, Hide, reset/submit form sowie das Setzen des Optional-Content-Zustands. Die Rendition-Aktion der Bildschirmannotation aus §13 ist zurückgestellt: Sie ist für künftige Arbeit vorgesehen und noch nicht angebunden, verlassen Sie sich daher nicht darauf, dass sie als unterstützte Aktion verfügbar ist. Action::withNext() baut die Aktionskette auf, die von einem einzelnen Auslöserereignis ausgeführt wird. PageTransition modelliert einen Präsentationsübergang. FileAttachment bettet eine Datei aus einem Pfad oder einem Byte-String ein und kennzeichnet sie mit einer AFRelationship (dem Enum der zugehörigen Dateibeziehung). Sie gibt ein FileAttachmentResult zurück und schreibt über writeAttachments(). Die Core-Manager sind @since 1.0.0. Die Aktionshierarchie ist @since 2.1.0. Der FileAttachment-Konstruktor und AFRelationship kamen mit @since 1.8.0 / @since 1.1.0 hinzu.

API-Oberfläche

Klasse	Wichtige Mitglieder	Rolle
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	Annotations-Builder mit Injection-sicheren Eingaben (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	Interne Links, benannte Sprungziele, URL-Annotationen (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	Dokument-Outline-Baum (Lesezeichen) (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	Inhaltsverzeichnis auf der Seite (@since 1.0.0)
Action (Interface)	subtype(), toDictionary(), withNext(), nextChain()	Auslöser-Aktion + Aktionskette (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	Seitenübergang für Präsentationen (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	Eingebettete Dateianhänge (@since 1.0.0)
AFRelationship (Enum)	toPdfName()	Zugehörige Dateibeziehung (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	Unveränderliche Menge von Annotations-Flags (@since 1.2.0)

Führen Sie composer docs:generate-api-php -- --module=Navigation aus, um die vollständige PHPDoc-Tabelle zu erhalten.

Codebeispiel — Schnellstart

Quelle: examples/12-bookmarks-and-toc.php baut das Dokument-Outline über die High-Level-Fassade auf, die BookmarkManager umschließt. So arbeiten Sie direkt mit dem 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.
}

Codebeispiel — Produktion

Betten Sie einen Anhang mit einer expliziten zugehörigen Dateibeziehung ein und prüfen Sie das Ergebnis, bevor das Dokument abgeschlossen wird.

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

Sonderfälle & Stolpersteine

• AnnotationManager normalisiert feindselige Eingaben stillschweigend: Ein ungültiger Subtyp wird zum Standard, ein Symbol, das kein Name ist, wird zum Standardsymbol, und fehlerhafte QuadPoints werden verworfen. Die Annotation wird trotzdem erzeugt — prüfen Sie Ihre Eingaben vorgelagert, wenn sie exakt berücksichtigt werden müssen.
• LinkManager::preallocateAnnotationObjects() muss ausgeführt werden, bevor der Writer Referenzen serialisiert, andernfalls lösen Linkziele ins Leere auf.
• Action::withNext() gibt eine neue Aktion mit der angehängten Kette zurück; das Interface ist für unveränderliche Verkettung ausgelegt, nicht für In-place-Mutation.
• FileAttachment::writeAttachments() erfordert eine aktive ObjectRegistry vom Writer. Der Aufruf des Managers für sich allein sammelt Absichten an, schreibt aber nichts, bis der Writer ihn ansteuert.
• AnnotationFlags ist eine unveränderliche Flag-Menge. with()/without() geben eine neue Instanz zurück; das Original bleibt unverändert.

Leistung

Das Sammeln von Annotationen, Links und Lesezeichen ist O(n) in der Anzahl der Elemente ohne Reflow. Die Kosten für eingebettete Dateianhänge werden von der eingebetteten Bytegröße dominiert, nicht vom Manager. Die standardmäßige Referenzlast bleibt innerhalb des Budgets von 1500 ms Wall-Zeit / 64 MB Spitzenverbrauch. Das Reproduzierbarkeitsprofil ist structural: Objektnummern und die Trailer-/ID unterscheiden sich zwischen Durchläufen. Zwei Dokumente mit derselben Navigationsabsicht sind strukturell gleich, aber nicht byte-identisch.

Sicherheitshinweise

AnnotationManager behandelt Annotations-Subtyp, Symbol und QuadPoints als nicht vertrauenswürdig: Jeder Wert wird anhand einer Allow-List oder eines Musters validiert, und ein ungültiger Wert wird ersetzt, statt unverändert geschrieben zu werden. Damit wird ein PDF-Name-Injection-Vektor geschlossen. LinkManager::addUrlAnnotation() kodiert eine URL in eine Link-Aktion. Der Konsument trägt die Vertrauensverantwortung für die URL — eine feindselige URL ist eine gültige URL, bereinigen Sie daher Ziele, bevor Sie sie hinzufügen. FileAttachment bettet beliebige Bytes ein. Begrenzen Sie die eingebettete Größe und behandeln Sie die Anhangquelle als nicht vertrauenswürdig, wenn sie von einem Benutzer stammt. Siehe das Bedrohungsmodell der Engine unter /modules/core/security/.

Konformität

Die Strukturen, die dieses Modul ausgibt, folgen ISO 32000-2 §12 — Annotationen, Aktionen, Sprungziele — sowie der Dokument-Outline-Hierarchie. Funktionsspezifische Klauselverweise (Annotationssymbole §12.5.6.4, Textmarkierungs-QuadPoints §12.5.6.10, Aktionen §12.6) sind direkt in src/Navigation/ dokumentiert und werden von tests/Unit/Navigation/ abgedeckt. Dies sind Implementierungsfakten, keine Aussage über die durchgängige PDF-2.0-Konformität. Die Konformität des gesamten Dokuments wird von den Oracle- und Golden-Suites validiert, die unter /modules/core/conformance/ beschrieben sind.

Siehe auch

• Document-Modul
• Multimedia-Modul — die Rendition-Objekte, die von einer Rendition-Aktion abgespielt werden.
• Writer-Modul — serialisiert die Navigationsstrukturen.
• Konformitätsübersicht
• Sicherheitsmodell der Engine