Gezinme: ek açıklamalar, bağlantılar, ana hatlar, eylemler ve dosya ekleri

Genel bakış

Navigation modülü, Taşınabilir Belge Biçimi’nin (PDF) etkileşimli katmanını oluşturur. Ek açıklamaları, bağlantı ve URL ek açıklamalarını, belge ana hattını (yer imleri), içindekiler tablosunu, eylemleri ve tetikleyici zincirlerini, sayfa geçişlerini, gömülü dosya eklerini ve bunlara bağlı ilişkili dosya ilişkilerini kapsar.

Kurulum

composer require nextpdf/core:^3

Kavramsal genel bakış

ISO 32000-2 §12, bir PDF belgesinin etkileşimli özelliklerini tanımlar: ek açıklamalar, eylemler, hedefler ve belge ana hattı. Bu modül, söz konusu katmanı motor içinde kodlar. Yönetici sınıfları amacı toplar; değer nesneleri de bu yöneticilerin ürettiği verileri taşır.

AnnotationManager en geniş kapsamlı giriş noktasıdır. Metin, serbest metin, çizgi, kare, daire, çokgen, çoklu çizgi, mürekkep ve metin işaretleme ek açıklamaları (vurgu ve altı çizili) ekler. Düşmanca girdiye karşı dayanıklı olacak şekilde tasarlanmıştır: bilinmeyen bir ek açıklama alt türü güvenli bir varsayılanla değiştirilir, geçerli bir PDF ad belirteci olmayan bir simge adı değiştirilir ve metin işaretleme QuadPoints değerlerinde kayan nokta değeri sayısı sekizin katı olmalıdır; aksi takdirde atılırlar. Bu denetimler doğrulama kolaylığı değil, PDF enjeksiyonuna karşı savunmadır. LinkManager dahili bağlantıları, adlandırılmış hedefleri ve URL ek açıklamalarını işler. Writer’ın serileştirmeden önce başvurabilmesi için ek açıklama nesnelerini önceden ayırır.

BookmarkManager ve TocBuilder gezinme hiyerarşisini oluşturur. Belge ana hattı, görüntüleyicinin kenar çubuğunda gösterilen yer imi ağacıdır. TocBuilder sayfa içi bir içindekiler tablosu oluşturur ve leader/width yerleşimi için FontMetrics kullanabilir. OutlineAutoGenerator belge yapısından bir ana hat türetir.

Söz konusu Action hiyerarşisi, NextPDF\Navigation\Action altında tetikleyici güdümlü davranışı modeller: GoTo (uzak ve gömülü), başlatma, adlandırılmış, gizleme, formu reset/submit ve isteğe bağlı içerik durumunu ayarlama. §13 ekran ek açıklaması işleme eylemi ertelenmiştir; bu, gelecekteki çalışma kapsamındadır ve henüz bağlanmamıştır. Bunu desteklenen bir eylem olarak kullanmayın. Action::withNext() tek bir tetikleyici olay için çalışan eylem zincirini oluşturur. PageTransition bir sunum geçişini modeller. FileAttachment bir dosyayı bir dosya yolundan veya bayt dizesinden gömer ve onu bir AFRelationship (ilişkili dosya ilişkisi enum’u) ile etiketler. Bir FileAttachmentResult döndürür ve writeAttachments() aracılığıyla yazar. Çekirdek yöneticiler @since 1.0.0 sürümündendir. Eylem hiyerarşisi @since 2.1.0 sürümündendir. FileAttachment kurucusu ve AFRelationship sırasıyla @since 1.8.0 / @since 1.1.0 sürümlerinde eklenmiştir.

API yüzeyi

Sınıf	Temel üyeler	Rol
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	Enjeksiyona karşı güvenli girdilerle ek açıklama oluşturucu (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	Dahili bağlantılar, adlandırılmış hedefler, URL ek açıklamaları (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	Belge ana hattı (yer imi) ağacı (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	Sayfa içi içindekiler tablosu (@since 1.0.0)
Action (arabirim)	subtype(), toDictionary(), withNext(), nextChain()	Tetikleyici eylem + eylem zinciri (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	Sunum sayfası geçişi (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	Gömülü dosya ekleri (@since 1.0.0)
AFRelationship (enum)	toPdfName()	İlişkili dosya ilişkisi (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	Değiştirilemez ek açıklama bayrak kümesi (@since 1.2.0)

Tam PHPDoc tablosunu oluşturmak için composer docs:generate-api-php -- --module=Navigation komutunu çalıştırın.

Kod örneği — hızlı başlangıç

examples/12-bookmarks-and-toc.php belge ana hattını, BookmarkManager sınıfını saran üst düzey cephe aracılığıyla oluşturur. Yöneticiyi doğrudan kullanmak isterseniz:

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

Kod örneği — üretim

Açıkça belirtilmiş bir ilişkili dosya ilişkisiyle bir eki gömün, ardından belgeyi sonlandırmadan önce sonucu denetleyin.

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

Uç durumlar ve dikkat edilecek noktalar

• AnnotationManager düşmanca girdiyi sessizce normalleştirir: geçersiz bir alt tür varsayılan hâline gelir, ad olmayan bir simge varsayılan simge hâline gelir ve hatalı biçimlendirilmiş QuadPoints değerleri atılır. Ek açıklama yine de üretilir; girdilerin olduğu gibi dikkate alınmasını istiyorsanız bunları üst akışta doğrulayın.
• LinkManager::preallocateAnnotationObjects(), Writer’ın başvuruları serileştirmesinden önce çalışmalıdır; aksi takdirde bağlantı hedefleri hiçbir nesneye çözümlenmez.
• Action::withNext(), zinciri eklenmiş yeni bir eylem döndürür; arabirim, yerinde değiştirmeyi değil, değiştirilemez zincirlemeyi destekler.
• FileAttachment::writeAttachments(), Writer’dan canlı bir ObjectRegistry gerektirir. Tek başına çağrıldığında yönetici amacı biriktirir, ancak Writer onu yönlendirene kadar hiçbir şey yazmaz.
• AnnotationFlags değiştirilemez bir bayrak kümesidir. with()/without() yeni bir örnek döndürür; özgün örnek değişmeden kalır.

Performans

Ek açıklama, bağlantı ve yer imi biriktirme, öğe sayısı bakımından O(n) karmaşıklığındadır ve yeniden akış yapmaz. Gömülü dosya eki maliyeti, yönetici ek yükü tarafından değil, gömülü bayt boyutu tarafından belirlenir. Varsayılan referans iş yükü, 1500 ms duvar süresi / 64 MB tepe bütçesinin içinde kalır. Yeniden üretilebilirlik profili structural şeklindedir: nesne numaraları ve fragman /ID değeri çalıştırmalar arasında farklılık gösterir. Aynı gezinme amacına sahip iki belge yapısal olarak eşittir, ancak bayt düzeyinde özdeş değildir.

Güvenlik notları

AnnotationManager, ek açıklama alt türünü, simgesini ve QuadPoints değerlerini güvenilmez olarak ele alır. Her değeri bir izin listesine veya desene göre doğrular ve hatalı bir değeri olduğu gibi yazmak yerine değiştirir. Bu, bir PDF ad enjeksiyonu vektörünü kapatır. LinkManager::addUrlAnnotation() bir URL’yi bir bağlantı eylemine kodlar. URL, tüketicinin güven sınırı olmaya devam eder: düşmanca bir URL yine de geçerli olabilir, bu nedenle hedefleri eklemeden önce temizleyin. FileAttachment rastgele baytları gömer. Gömülü boyutu sınırlayın ve kullanıcının sağladığı her ek kaynağını güvenilmez olarak ele alın. Motor tehdit modeli için /modules/core/security/ bölümüne bakın.

Uyumluluk

Bu modülün ürettiği yapılar; ek açıklamalar, eylemler, hedefler ve belge ana hattı hiyerarşisi için ISO 32000-2 §12’yi izler. Özellik temelli madde başvuruları (ek açıklama simgeleri §12.5.6.4, metin işaretleme QuadPoints §12.5.6.10, eylemler §12.6), src/Navigation/ içinde satır içi olarak belgelenmiştir ve tests/Unit/Navigation/ tarafından sınanmaktadır. Bunlar uygulama gerçekleridir, uçtan uca PDF 2.0 uyumluluğu beyanı değildir. Tam belge uyumluluğu, /modules/core/conformance/ bölümünde açıklanan oracle ve altın takımlar tarafından doğrulanır.

Ayrıca bakınız

• Document modülü
• Multimedia modülü — bir işleme eylemi tarafından oynatılan işleme nesneleri.
• Writer modülü — gezinme yapılarını serileştirir.
• Uyumluluk genel bakışı
• Motor güvenlik modeli