Navigasi: anotasi, tautan, outline, aksi, dan lampiran

Sekilas pandang

Modul Navigation membangun lapisan interaktif dalam Portable Document Format (PDF). Modul ini mencakup anotasi, anotasi tautan dan Uniform Resource Locator (URL), outline dokumen (bookmark), daftar isi, aksi dan rantai pemicu, transisi halaman, serta lampiran berkas tersemat beserta relasi berkas terkaitnya.

Instalasi

composer require nextpdf/core:^3

Tinjauan konseptual

ISO 32000-2 §12 mendefinisikan fitur interaktif dalam dokumen PDF: anotasi, aksi, destinasi, dan outline dokumen. Modul ini mengodekan lapisan tersebut dalam bentuk yang dapat diproses mesin. Kelas manager mengumpulkan intent; value object membawa data yang dipancarkan manager tersebut.

AnnotationManager adalah titik masuk terluas. Manager ini menambahkan anotasi teks, free-text, garis, persegi, lingkaran, poligon, polyline, ink, dan text-markup (sorotan dan garis bawah). Manager ini diperkeras terhadap input berbahaya: subtipe anotasi yang tidak dikenal akan dialihkan ke default yang aman, nama ikon yang bukan token nama PDF yang valid akan diganti, dan QuadPoints text-markup harus diberikan sebagai kelipatan delapan nilai float atau akan dibuang. Pemeriksaan ini merupakan pertahanan terhadap injeksi PDF, bukan sekadar kemudahan validasi. LinkManager menangani tautan internal, destinasi bernama, dan anotasi URL. Manager ini mengalokasikan objek anotasi terlebih dahulu agar Writer dapat merujuknya sebelum serialisasi.

BookmarkManager dan TocBuilder membangun hierarki navigasi. Outline dokumen adalah pohon bookmark yang ditampilkan oleh penampil di bilah sampingnya. TocBuilder merender daftar isi pada halaman dan dapat menggunakan FontMetrics untuk tata letak leader/width. OutlineAutoGenerator menurunkan outline dari struktur dokumen.

Hierarki Action di bawah NextPDF\Navigation\Action memodelkan perilaku yang digerakkan oleh pemicu: GoTo (remote dan embedded), launch, named, hide, form reset/submit, dan penyetelan state optional-content. Aksi rendition untuk anotasi layar §13 ditangguhkan; ini merupakan pekerjaan mendatang dan belum disambungkan. Jangan mengandalkannya sebagai aksi yang didukung. Action::withNext() membangun rantai aksi yang dijalankan untuk satu peristiwa pemicu. PageTransition memodelkan transisi presentasi. FileAttachment menyematkan berkas dari sebuah path atau string byte dan menandainya dengan AFRelationship (enum relasi berkas terkait). Manager ini mengembalikan FileAttachmentResult dan menulis melalui writeAttachments(). Manager inti adalah @since 1.0.0. Hierarki aksi adalah @since 2.1.0. Konstruktor FileAttachment dan AFRelationship hadir pada @since 1.8.0 / @since 1.1.0.

Permukaan API

Kelas	Anggota utama	Peran
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	Pembuat anotasi dengan input yang aman terhadap injeksi (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	Tautan internal, destinasi bernama, anotasi URL (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	Pohon outline dokumen (bookmark) (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	Daftar isi pada halaman (@since 1.0.0)
Action (antarmuka)	subtype(), toDictionary(), withNext(), nextChain()	Aksi pemicu + rantai aksi (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	Transisi halaman presentasi (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	Lampiran berkas tersemat (@since 1.0.0)
AFRelationship (enum)	toPdfName()	Relasi berkas terkait (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	Kumpulan flag anotasi yang immutable (@since 1.2.0)

Jalankan composer docs:generate-api-php -- --module=Navigation untuk menghasilkan tabel PHPDoc lengkap.

Contoh kode — Mulai cepat

examples/12-bookmarks-and-toc.php membangun outline dokumen melalui fasad tingkat tinggi yang membungkus BookmarkManager. Untuk memakai manager secara langsung:

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

Contoh kode — Produksi

Sematkan sebuah lampiran dengan relasi berkas terkait yang eksplisit, lalu periksa hasilnya sebelum memfinalisasi dokumen.

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

Kasus tepi & jebakan

• AnnotationManager menormalkan input berbahaya secara diam-diam: subtipe yang tidak valid menjadi default, ikon yang bukan nama menjadi ikon default, dan QuadPoints yang cacat dibuang. Anotasi tetap dihasilkan; lakukan validasi input di hulu jika Anda perlu nilai tersebut dipertahankan secara persis.
• LinkManager::preallocateAnnotationObjects() harus dijalankan sebelum Writer melakukan serialisasi referensi, atau target tautan tidak akan terselesaikan.
• Action::withNext() mengembalikan aksi baru dengan rantai terlampir; antarmuka ini mendukung perangkaian immutable, bukan mutasi in-place.
• FileAttachment::writeAttachments() memerlukan ObjectRegistry aktif dari Writer. Jika dipanggil secara terisolasi, manager mengakumulasi intent tetapi tidak menulis apa pun sampai Writer menjalankannya.
• AnnotationFlags adalah kumpulan flag yang immutable. with()/without() mengembalikan instans baru; aslinya tidak berubah.

Kinerja

Akumulasi anotasi, tautan, dan bookmark bersifat O(n) terhadap jumlah item dan tidak melakukan reflow. Biaya lampiran berkas tersemat didominasi oleh ukuran byte yang disematkan, bukan overhead manager. Beban kerja referensi standar tetap berada dalam anggaran 1500 ms wall / 64 MB peak. Profil reproduktibilitasnya adalah structural: nomor objek dan trailer /ID berbeda antar-eksekusi. Dua dokumen dengan intent navigasi yang sama setara secara struktural, tetapi tidak identik secara byte.

Catatan keamanan

AnnotationManager memperlakukan subtipe anotasi, ikon, dan QuadPoints sebagai tidak tepercaya. Manager ini memvalidasi setiap nilai terhadap allow-list atau pola dan mengganti nilai yang buruk alih-alih meneruskannya. Ini menutup vektor injeksi nama PDF. LinkManager::addUrlAnnotation() mengodekan URL menjadi aksi tautan. URL tetap menjadi batas kepercayaan bagi konsumen: URL berbahaya tetap bisa valid, jadi bersihkan destinasi sebelum menambahkannya. FileAttachment menyematkan byte sembarang. Batasi ukuran yang disematkan, dan perlakukan setiap sumber lampiran yang disediakan pengguna sebagai tidak tepercaya. Lihat model ancaman mesin di /modules/core/security/.

Kesesuaian

Struktur yang dihasilkan modul ini mengikuti ISO 32000-2 §12 untuk anotasi, aksi, destinasi, dan hierarki outline dokumen. Referensi klausa per fitur (ikon anotasi §12.5.6.4, QuadPoints text-markup §12.5.6.10, aksi §12.6) didokumentasikan secara inline di src/Navigation/ dan diuji oleh tests/Unit/Navigation/. Ini adalah fakta implementasi, bukan pernyataan kesesuaian PDF 2.0 menyeluruh. Kesesuaian dokumen secara penuh divalidasi oleh oracle dan golden suite yang dijelaskan di /modules/core/conformance/.

Lihat juga

• Modul Document
• Modul Multimedia — objek rendition yang diputar oleh aksi rendition.
• Modul Writer — melakukan serialisasi struktur navigasi.
• Tinjauan kesesuaian
• Model keamanan mesin