Bağlantılar ve metin ek açıklamaları ekleme

Bir bakışta

Üç etkileşimli öğe eklemek için bu reçeteyi kullanın: başka bir sayfaya götüren bir iç bağlantı, bir Tekdüzen Kaynak Konumlandırıcı (URL) açan bir harici bağlantı ve yapışkan not olarak da bilinen bir metin ek açıklaması. Bu reçete, examples/17-links.php ve examples/29-annotations.php dosyalarını temel alır.

Tıklanabilir bağlantı, bir ISO 32000-2 bağlantı ek açıklamasıdır: bir hedefe veya eyleme yönelik bir hipermetin bağlantısı. Yapışkan not ise bir metin ek açıklamasıdır; kapalıyken simge, açıkken açılır pencere olarak görünür.

Kurulum

composer require nextpdf/core:^3

İsteğe bağlı bir uzantı gerekmez. Bağlantı ve ek açıklama API’si, 1.0.0 sürümünden beri kararlıdır ve 8.1–8.4 geriye taşıma matrisinde çalışır.

Kavramsal genel bakış

İç bağlantılar, ileri başvuruları destekleyen üç çağrıdan oluşan bir kalıp izler:

addLink() bir bağlantı tanımlayıcısı (bir int) ayırır.
link($x, $y, $w, $h, $id) bu id’ye bağlı tıklanabilir bir dikdörtgen yerleştirir.
setLink($id, $pageIndex, $y) id’yi bir hedef sayfaya (sıfır tabanlı) ve Y değerine bağlar.

Henüz var olmayan bir sayfaya bağlantı verdiğinizde 3. adımı 2. adımdan sonra çağırın. Hedef, açık hedef biçimini kullanır. ISO 32000-2 §12.3.2.2, [page /XYZ left top zoom] biçimini tanımlar; burada null olan bir bileşen, okuyucunun geçerli değerini korur.

Harici bağlantı için bir int yerine bir URL dizesi’ni link() işlevine geçirin. Ardından NextPDF, URI değeri zorunlu bir UTF-8 ASCII dizesi olan bir Tekdüzen Kaynak Tanımlayıcısı (URI) eylemi yayar. Kısayol olarak, write($height, $text, $link) URL eklenmiş satır içi metin çizer ve annotation($x, $y, $w, $h, $text) Text alt türünde bir yapışkan not yerleştirir. ISO 32000-2 bir bağlantı ek açıklaması için SubtypeLink değerini gerektirir ve metin ek açıklamasının simge ile açılır pencere davranışını tanımlar.

API yüzeyi

API yüzeyi, PHPDoc’tan oluşturulur. Bu reçete şu yöntemlere dayanır:

addLink(): int — bir iç bağlantı tanımlayıcısı ayırır.
setLink(int $linkId, int $pageIndex = -1, float $y = 0): static — bir id’yi bir hedef sayfaya (sıfır tabanlı) ve Y değerine bağlar.
link(float $x, float $y, float $w, float $h, string|int $link): static — tıklanabilir bir dikdörtgen oluşturur; int id iç bağlantıdır, dize ise harici bir URL’dir.
write(float $height, string $text, string $link = ''): static — isteğe bağlı bir URL ile satır içi metin yazar.
annotation(float $x, float $y, float $w, float $h, string $text, string $subtype = 'Text'): static — bir yapışkan not ek açıklaması ekler.

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

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$jump = $doc->addLink();             // 1. reserve an id (forward reference)

$doc->addPage();
$doc->setFont('helvetica', 'B', 12);
$x = $doc->getX();
$y = $doc->getY();
$doc->cell(60, 10, 'Go to page 2', newLine: true);
$doc->link($x, $y, 60, 10, $jump);   // 2. clickable rectangle -> id

$doc->link($doc->getX(), $doc->getY(), 80, 10, 'https://nextpdf.dev'); // external

$doc->addPage();
$doc->setLink($jump, pageIndex: 1, y: 0); // 3. bind id to page 2 (index 1)
$doc->cell(0, 10, 'Destination (page 2).', newLine: true);
$doc->annotation(x: 180, y: 20, w: 10, h: 10, text: 'A reviewer note.');

$doc->save(getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/links.pdf');

Kod örneği — üretim

Bu, eksiksiz ve koşumda çalışmaya hazır bir örnektir. NEXTPDF_COOKBOOK_OUTPUT değerine uyar ve kendi entropisini eklemez.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Links and Annotations');

// Reserve the internal-link id before its destination page exists.
$linkToPage3 = $doc->addLink();

// Page 1 — source of the internal and external links.
$doc->addPage();
$doc->setFont('helvetica', 'B', 20);
$doc->cell(0, 14, 'Links and Annotations', newLine: true);
$doc->ln(6);

$doc->setFont('helvetica', 'B', 12);
$doc->setTextColor(0, 51, 153);
$linkX = $doc->getX();
$linkY = $doc->getY();
$doc->cell(60, 10, 'Go to Page 3', newLine: true);
$doc->link($linkX, $linkY, 60, 10, $linkToPage3); // internal: int id
$doc->setTextColor(0);
$doc->ln(6);

$doc->setFont('helvetica', 'B', 12);
$doc->setTextColor(0, 102, 204);
$doc->write(10, 'Visit https://nextpdf.dev', link: 'https://nextpdf.dev');
$doc->setTextColor(0);
$doc->ln(6);

$urlX = $doc->getX();
$urlY = $doc->getY();
$doc->cell(80, 10, 'NextPDF on GitHub', newLine: true);
$doc->link($urlX, $urlY, 80, 10, 'https://github.com/nextpdf-labs/nextpdf');

// Page 2 — intermediate.
$doc->addPage();
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Internal links can jump across pages; this page is '
    . 'skipped by the link on page 1.');

// Page 3 — destination + a sticky note.
$doc->addPage();
$doc->setLink($linkToPage3, pageIndex: 2, y: 0); // bind id to page 3 (index 2)
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 14, 'Page 3 — Link Target', newLine: true);
$doc->ln(4);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'You arrived via the internal link on page 1.');
$doc->annotation(
    x: 185, y: 40, w: 10, h: 10,
    text: 'Sticky note: appears as an icon; click to read this text.',
);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT') ?: __DIR__ . '/links.pdf';
$doc->save($out);

echo "Created links.pdf\n";

Uç durumlar ve tuzaklar

pageIndex sıfır tabanlıdır. setLink($id, pageIndex: 2, …) üçüncü sayfayı hedefler. Buradaki bir-eksik hataları en yaygın hatalardandır.
link() işlevinde dize ile int ayrımı. Bir int, addLink() işlevinden gelen bir iç hedef id’sidir. Bir dize, harici bir URL’dir. Yanlış türü geçirirseniz, hiçbir hata almadan yanlış türde bir bağlantı elde edersiniz.
Ayırdığınız her id’yi bağlayın. addLink() ile oluşturup setLink() ile hiç bağlamadığınız bir id’nin hedefi yoktur. Dikdörtgen tıklanabilir ancak işlevsizdir. save() işlevinden önce bağlayın.
Tıklanabilir alan dikdörtgendir, metin değildir. link() açıkça verilen x, y, w, h değerlerini alır. Görünür metni kapsayacak biçimde boyutlandırın. Motor sizin yerinize glifleri ölçmez.
Harici bağlantılar doğrulanmaz. NextPDF, URI’yi olduğu gibi saklar. Hedefin çözümlenip çözümlenmediğini veya güvenli olup olmadığını doğrulamaz. Bunu okuyucu çözümler.

Performans

Her bağlantı veya ek açıklama, sayfaya bir ek açıklama sözlüğü ekler. Maliyet öğe başına O(1)‘dir. Sayfa başına yüzlercesi bile 2000 ms / 64 MB bütçesinin oldukça içinde kalır.

Güvenlik notları

Harici bağlantı hedefleri olduğu gibi saklanır ve kitaplık tarafından değil, okuyucu tarafından çözümlenir. Kullanıcı tarafından sağlanan URL’leri güvenilmez olarak değerlendirin. Genellikle https olacak şekilde, şemayı izin listesine alın. javascript: ve file: şemalarını link() işlevine geçirmeden önce reddedin. Ek açıklama metni, okuyucunun kullanıcı arabiriminde (UI) görünür; bu nedenle kullanıcının denetimindeki not içeriğini uzunluk açısından sınırlandırın ve temizleyin. Bu reçetede hiçbir girdi ayrıştırması veya ağ erişimi gerçekleşmez.

Uyumluluk

İfade	Belirtim	Madde
Bir bağlantı ek açıklaması, bir hedefe veya bir eyleme yönelik bir hipermetin bağlantısıdır.	ISO 32000-2	§12.5.6.5
`Subtype` değeri, bir bağlantı ek açıklaması için `Link` olur.	ISO 32000-2	§12.5.6.5
Bir URI eyleminin `URI` değeri, zorunlu bir UTF-8 ASCII dizesidir.	ISO 32000-2	§12.6.4.8
Bir metin ek açıklaması, bir yapışkan nottur (kapalı = simge, açık = açılır pencere).	ISO 32000-2	§12.5.6.4
Açık hedef `[page /XYZ left top zoom]` biçimindedir; null geçerli değeri korur.	ISO 32000-2	§12.3.2.2

Yeniden üretilebilirlik profili — yapısal. Trailer’daki /ID ve tarih atomları her çalıştırmada değişir. Koşum bu atomları çıkarır, ardından qpdf ile normalleştirilmiş yapıyı karşılaştırır. Bu reçete, NextPDF’in yapıyı nasıl ürettiğini açıklar. Genel kapsamlı bir ISO 32000-2 uyumluluğu iddiası öne sürmez.

Ticari bağlam

Uygulanamaz. Bağlantılar ve metin ek açıklamaları, herhangi bir Premium kapısı olmayan Core yetenekleridir.