Nawigacja: adnotacje, odsyłacze, konspekty, akcje i załączniki

W skrócie

Moduł Navigation buduje warstwę interaktywną formatu Portable Document Format (PDF). Obejmuje adnotacje, adnotacje odsyłaczy i adresów Uniform Resource Locator (URL), konspekt dokumentu (zakładki), spis treści, akcje i łańcuchy wyzwalaczy, przejścia między stronami oraz załączniki w postaci osadzonych plików wraz z relacjami plików powiązanych.

Instalacja

composer require nextpdf/core:^3

Przegląd koncepcyjny

Norma ISO 32000-2 §12 definiuje interaktywne funkcje dokumentu PDF: adnotacje, akcje, miejsca docelowe oraz konspekt dokumentu. Ten moduł koduje tę warstwę dla silnika. Klasy menedżerów rejestrują intencję, a obiekty wartości przenoszą dane emitowane przez menedżery.

AnnotationManager jest najbardziej ogólnym punktem wejścia. Dodaje adnotacje tekstowe, wolnego tekstu, linii, prostokąta, okręgu, wielokąta, łamanej, odręczne oraz adnotacje znakowania tekstu (wyróżnienie i podkreślenie). Jest odporny na wrogie dane wejściowe: nieznany podtyp adnotacji jest normalizowany do bezpiecznej wartości domyślnej, nazwa ikony, która nie jest prawidłowym tokenem nazwy PDF, jest zastępowana, a wartości QuadPoints dla znakowania tekstu muszą być przekazane jako wielokrotność ośmiu liczb zmiennoprzecinkowych; w przeciwnym razie są odrzucane. Te kontrole są zabezpieczeniami przed wstrzykiwaniem do PDF, a nie udogodnieniami walidacyjnymi. LinkManager obsługuje odsyłacze wewnętrzne, nazwane miejsca docelowe oraz adnotacje URL. Wstępnie alokuje obiekty adnotacji, aby Writer mógł odwoływać się do nich przed serializacją.

BookmarkManager i TocBuilder budują hierarchię nawigacji. Konspekt dokumentu to drzewo zakładek wyświetlane przez przeglądarkę w pasku bocznym. TocBuilder renderuje spis treści umieszczony na stronie i może używać FontMetrics przy wyznaczaniu układu leader/width. OutlineAutoGenerator wyprowadza konspekt ze struktury dokumentu.

Hierarchia Action w przestrzeni NextPDF\Navigation\Action modeluje zachowanie sterowane wyzwalaczami: GoTo (zdalne i osadzone), launch, named, hide, reset/submit formularza oraz ustawienie stanu treści opcjonalnej. Akcja odtwarzania adnotacji ekranowej z §13 jest odłożona; to praca na przyszłość, która nie jest jeszcze podłączona. Nie traktuj jej jako obsługiwanej akcji. Action::withNext() buduje łańcuch akcji uruchamiany dla pojedynczego zdarzenia wyzwalającego. PageTransition modeluje przejście w prezentacji. FileAttachment osadza plik ze ścieżki albo z ciągu bajtów i oznacza go wartością AFRelationship (typem wyliczeniowym relacji pliku powiązanego). Zwraca FileAttachmentResult i zapisuje za pośrednictwem writeAttachments(). Podstawowe menedżery są dostępne od @since 1.0.0. Hierarchia akcji jest dostępna od @since 2.1.0. Konstruktor FileAttachment oraz AFRelationship pojawiły się w @since 1.8.0 / @since 1.1.0.

Powierzchnia API

Klasa	Kluczowe składowe	Rola
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	Tworzenie adnotacji z danymi wejściowymi zabezpieczonymi przed wstrzykiwaniem (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	Odsyłacze wewnętrzne, nazwane miejsca docelowe, adnotacje URL (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	Drzewo konspektu dokumentu (zakładek) (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	Spis treści umieszczony na stronie (@since 1.0.0)
Action (interfejs)	subtype(), toDictionary(), withNext(), nextChain()	Akcja wyzwalacza + łańcuch akcji (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	Przejście między stronami prezentacji (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	Załączniki w postaci osadzonych plików (@since 1.0.0)
AFRelationship (typ wyliczeniowy)	toPdfName()	Relacja pliku powiązanego (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	Niemodyfikowalny zestaw flag adnotacji (@since 1.2.0)

Uruchom composer docs:generate-api-php -- --module=Navigation, aby wygenerować pełną tabelę PHPDoc.

Przykład kodu — szybki start

examples/12-bookmarks-and-toc.php buduje konspekt dokumentu za pomocą fasady wysokiego poziomu opakowującej BookmarkManager. Aby użyć menedżera bezpośrednio:

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

Przykład kodu — produkcja

Osadź załącznik z jawną relacją pliku powiązanego, a następnie sprawdź wynik przed sfinalizowaniem dokumentu.

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

Przypadki brzegowe i pułapki

• AnnotationManager po cichu normalizuje wrogie dane wejściowe: nieprawidłowy podtyp staje się wartością domyślną, nieprawidłowa nazwa ikony staje się nazwą domyślną, a zniekształcone QuadPoints są odrzucane. Adnotacja i tak jest tworzona; zwaliduj dane wejściowe wcześniej, jeśli wymagasz ich dokładnego odwzorowania.
• LinkManager::preallocateAnnotationObjects() musi zostać uruchomione, zanim Writer zserializuje odwołania; w przeciwnym razie cele odsyłaczy nie zostaną rozwiązane.
• Action::withNext() zwraca nową akcję z dołączonym łańcuchem; interfejs obsługuje niemodyfikowalne łączenie w łańcuch, a nie modyfikację w miejscu.
• FileAttachment::writeAttachments() wymaga aktywnego ObjectRegistry z Writer. Menedżer uruchomiony w izolacji gromadzi intencję, ale niczego nie zapisuje, dopóki nie zostanie obsłużony przez Writer.
• AnnotationFlags to niemodyfikowalny zestaw flag. with()/without() zwracają nowe wystąpienie; oryginał pozostaje niezmieniony.

Wydajność

Gromadzenie adnotacji, odsyłaczy i zakładek ma złożoność O(n) względem liczby elementów i nie wymaga ponownego układania treści. Koszt załącznika w postaci osadzonego pliku jest zdominowany przez rozmiar osadzonych bajtów, a nie przez narzut menedżera. Domyślne obciążenie referencyjne mieści się w budżecie 1500 ms czasu rzeczywistego / 64 MB szczytowego zużycia pamięci. Profil odtwarzalności to structural: numery obiektów oraz /ID w zwiastunie różnią się między uruchomieniami. Dwa dokumenty o tej samej intencji nawigacyjnej są równoważne strukturalnie, ale nie są identyczne bajt po bajcie.

Uwagi dotyczące bezpieczeństwa

AnnotationManager traktuje podtyp adnotacji, ikonę oraz QuadPoints jako niezaufane. Waliduje każdą wartość względem listy dozwolonych wartości albo wzorca i zastępuje błędną wartość, zamiast przepuszczać ją dalej. Zamyka to wektor wstrzykiwania nazw PDF. LinkManager::addUrlAnnotation() koduje adres URL w akcję odsyłacza. Adres URL wyznacza granicę zaufania po stronie konsumenta: wrogi adres URL nadal może być prawidłowy, dlatego oczyść miejsca docelowe przed ich dodaniem. FileAttachment osadza dowolne bajty. Ogranicz rozmiar osadzonych danych i traktuj każde źródło załącznika dostarczone przez użytkownika jako niezaufane. Zobacz model zagrożeń silnika w /modules/core/security/.

Zgodność

Struktury emitowane przez ten moduł są zgodne z normą ISO 32000-2 §12 w zakresie adnotacji, akcji, miejsc docelowych oraz hierarchii konspektu dokumentu. Odwołania do klauzul dotyczących poszczególnych funkcji (ikony adnotacji §12.5.6.4, znakowanie tekstu QuadPoints §12.5.6.10, akcje §12.6) są udokumentowane bezpośrednio w src/Navigation/ i sprawdzane przez tests/Unit/Navigation/. Są to fakty dotyczące implementacji, a nie deklaracja pełnej zgodności z PDF 2.0. Zgodność całego dokumentu jest walidowana przez wyrocznię oraz zestawy wzorcowe opisane w /modules/core/conformance/.

Zobacz także

• Moduł Document
• Moduł Multimedia — obiekty odtwarzania uruchamiane przez akcję odtwarzania.
• Moduł Writer — serializuje struktury nawigacji.
• Przegląd zgodności
• Model bezpieczeństwa silnika