Dodawanie odnośników i adnotacji tekstowych

W skrócie

Ten przepis pokazuje, jak dodać trzy elementy interaktywne: odnośnik wewnętrzny przenoszący do innej strony, odnośnik zewnętrzny otwierający adres URL (Uniform Resource Locator) oraz adnotację tekstową, zwaną także karteczką samoprzylepną. Opiera się na plikach examples/17-links.php oraz examples/29-annotations.php.

Klikalny odnośnik jest adnotacją odnośnika w rozumieniu ISO 32000-2: hipertekstowym odnośnikiem do miejsca docelowego lub akcji. Karteczka samoprzylepna jest adnotacją tekstową. Po zamknięciu wyświetla się jako ikona, a po otwarciu jako okienko wyskakujące.

Instalacja

composer require nextpdf/core:^3

Żadne opcjonalne rozszerzenie nie jest wymagane. API odnośników i adnotacji jest stabilne od wersji 1.0.0 i obsługiwane w macierzy backportów 8.1–8.4.

Przegląd koncepcyjny

Odnośniki wewnętrzne korzystają ze wzorca trzech wywołań, który obsługuje odwołania do przodu:

addLink() rezerwuje identyfikator odnośnika (typu int).
link($x, $y, $w, $h, $id) umieszcza klikalny prostokąt powiązany z tym identyfikatorem.
setLink($id, $pageIndex, $y) wiąże identyfikator ze stroną docelową (liczoną od zera) i współrzędną Y.

Krok 3 wykonaj po kroku 2, gdy tworzysz odnośnik do strony, która jeszcze nie istnieje. Miejsce docelowe jest zapisywane jako jawne miejsce docelowe. ISO 32000-2 §12.3.2.2 definiuje [page /XYZ left top zoom], gdzie składnik o wartości null zachowuje bieżącą wartość czytnika.

W przypadku odnośnika zewnętrznego przekaż do link() ciąg znaków URL zamiast wartości int. NextPDF emituje wtedy akcję typu URI (Uniform Resource Identifier), której pole URI jest wymaganym ciągiem znaków ASCII w kodowaniu UTF-8. write($height, $text, $link) działa jako skrót: rysuje tekst w wierszu z dołączonym adresem URL, a annotation($x, $y, $w, $h, $text) umieszcza karteczkę samoprzylepną podtypu Text. ISO 32000-2 wymaga SubtypeLink dla adnotacji odnośnika oraz definiuje zachowanie ikony i okienka wyskakującego adnotacji tekstowej.

Powierzchnia API

Opis API jest generowany z PHPDoc. Ten przepis opiera się na następujących metodach:

addLink(): int — rezerwuje identyfikator odnośnika wewnętrznego.
setLink(int $linkId, int $pageIndex = -1, float $y = 0): static — wiąże identyfikator ze stroną docelową (liczoną od zera) i współrzędną Y.
link(float $x, float $y, float $w, float $h, string|int $link): static — tworzy klikalny prostokąt; identyfikator typu int jest wewnętrzny, a ciąg znaków oznacza zewnętrzny adres URL.
write(float $height, string $text, string $link = ''): static — wypisuje tekst w wierszu z opcjonalnym adresem URL.
annotation(float $x, float $y, float $w, float $h, string $text, string $subtype = 'Text'): static — dodaje adnotację w formie karteczki samoprzylepnej.

Przykład kodu — szybki start

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

Przykład kodu — wersja produkcyjna

To kompletny przykład gotowy do uruchomienia w środowisku testowym. Uwzględnia zmienną NEXTPDF_COOKBOOK_OUTPUT i nie wprowadza dodatkowej entropii.

<?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";

Przypadki brzegowe i pułapki

pageIndex jest liczony od zera. setLink($id, pageIndex: 2, …) wskazuje trzecią stronę. Pomyłki o jeden są tutaj najczęstsze.
Ciąg znaków a int w link(). Wartość int to identyfikator wewnętrznego miejsca docelowego pochodzący z addLink(). Ciąg znaków oznacza zewnętrzny adres URL. Jeśli przekażesz nieprawidłowy typ, powstanie niewłaściwy rodzaj odnośnika bez zgłoszenia błędu.
Powiąż każdy zarezerwowany identyfikator. Identyfikator z addLink(), którego nigdy nie powiążesz za pomocą setLink(), nie ma miejsca docelowego. Prostokąt jest klikalny, ale bezczynny. Powiąż go przed save().
Obszarem klikalnym jest prostokąt, a nie tekst. link() przyjmuje jawne x, y, w, h. Dobierz jego rozmiar tak, aby pokrywał widoczny tekst. Silnik nie mierzy glifów automatycznie.
Odnośniki zewnętrzne nie są weryfikowane. NextPDF przechowuje URI dosłownie. Nie sprawdza, czy cel daje się rozwiązać ani czy jest bezpieczny. Cel rozwiązuje czytnik.

Wydajność

Każdy odnośnik lub adnotacja dodaje do strony jeden słownik adnotacji. Koszt wynosi O(1) na element. Setki elementów na stronę z powodzeniem mieszczą się w budżecie 2000 ms / 64 MB.

Uwagi dotyczące bezpieczeństwa

Cele odnośników zewnętrznych są przechowywane dosłownie i rozwiązywane przez czytnik, a nie przez bibliotekę. Adresy URL pochodzące od użytkownika traktuj jako niezaufane. Dopuszczaj tylko dozwolone schematy, zwykle https. Odrzuć javascript: oraz file:, zanim przekażesz je do link(). Tekst adnotacji pojawia się w interfejsie użytkownika (UI) czytnika, dlatego ograniczaj długość i odkażaj kontrolowaną przez użytkownika treść notatek. W tym przepisie nie zachodzi żadne parsowanie danych wejściowych ani dostęp do sieci.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Adnotacja odnośnika to odnośnik hipertekstowy do miejsca docelowego lub akcji.	ISO 32000-2	§12.5.6.5
Dla adnotacji odnośnika `Subtype` wynosi `Link`.	ISO 32000-2	§12.5.6.5
Pole `URI` akcji typu URI jest wymaganym ciągiem znaków ASCII w kodowaniu UTF-8.	ISO 32000-2	§12.6.4.8
Adnotacja tekstowa to karteczka samoprzylepna (zamknięta = ikona, otwarta = okienko wyskakujące).	ISO 32000-2	§12.5.6.4
Jawne miejsce docelowe `[page /XYZ left top zoom]`; null zachowuje bieżącą wartość.	ISO 32000-2	§12.3.2.2

Profil odtwarzalności — strukturalny. Atomy /ID oraz daty w przyczepce zmieniają się przy każdym zapisie. Środowisko testowe usuwa te atomy, a następnie porównuje strukturę znormalizowaną przez qpdf. Ten przepis opisuje, w jaki sposób NextPDF tworzy tę strukturę. Nie stanowi ogólnej deklaracji zgodności z ISO 32000-2.

Kontekst komercyjny

Nie dotyczy. Odnośniki i adnotacje tekstowe to funkcje Core, niewymagające Premium.