Koppelingen en tekstannotaties toevoegen

In een oogopslag

Gebruik dit recipe om drie interactieve elementen toe te voegen: een interne koppeling die naar een andere pagina springt, een externe koppeling die een Uniform Resource Locator (URL) opent en een tekstannotatie, ook wel plaknotitie genoemd. Het sluit aan op examples/17-links.php en examples/29-annotations.php.

Een aanklikbare koppeling is volgens ISO 32000-2 een koppelingsannotatie: een hypertekstkoppeling naar een bestemming of een actie. Een plaknotitie is een tekstannotatie. In gesloten toestand verschijnt die als pictogram; geopend verschijnt die als pop-up.

Installeren

composer require nextpdf/core:^3

Er is geen optionele extensie vereist. De API voor koppelingen en annotaties is stabiel sinds 1.0.0 en werkt op de 8.1–8.4-backportmatrix.

Conceptueel overzicht

Interne koppelingen volgen een patroon met drie aanroepen, dat voorwaartse verwijzingen ondersteunt:

addLink() reserveert een koppelings-id (een int).
link($x, $y, $w, $h, $id) plaatst een aanklikbare rechthoek die aan die id is gekoppeld.
setLink($id, $pageIndex, $y) koppelt de id aan een bestemmingspagina (op nul gebaseerd) en Y.

Roep stap 3 na stap 2 aan wanneer je koppelt naar een pagina die nog niet bestaat. De bestemming gebruikt een expliciete bestemmingsvorm. ISO 32000-2 §12.3.2.2 definieert [page /XYZ left top zoom], waarbij een null-component de huidige waarde van de lezer behoudt.

Geef voor een externe koppeling een URL-tekenreeks door aan link() in plaats van een int. NextPDF genereert dan een Uniform Resource Identifier-actie (URI) waarvan de URI een vereiste UTF-8 ASCII-tekenreeks is. Als snelkoppeling tekent write($height, $text, $link) inline-tekst met een gekoppelde URL en plaatst annotation($x, $y, $w, $h, $text) een plaknotitie van het subtype Text. ISO 32000-2 vereist SubtypeLink voor een koppelingsannotatie en definieert het pictogram en het pop-upgedrag van de tekstannotatie.

API-oppervlak

Het API-oppervlak wordt gegenereerd uit PHPDoc. Dit recipe gebruikt de volgende methoden:

addLink(): int — reserveer een interne koppelings-id.
setLink(int $linkId, int $pageIndex = -1, float $y = 0): static — koppel een id aan een bestemmingspagina (op nul gebaseerd) en Y.
link(float $x, float $y, float $w, float $h, string|int $link): static — maak een aanklikbare rechthoek; een int-id is intern en een tekenreeks is een externe URL.
write(float $height, string $text, string $link = ''): static — schrijf inline-tekst met een optionele URL.
annotation(float $x, float $y, float $w, float $h, string $text, string $subtype = 'Text'): static — voeg een plaknotitie-annotatie toe.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

Dit is het volledige voorbeeld, klaar voor de harness. Het houdt rekening met NEXTPDF_COOKBOOK_OUTPUT en voegt zelf geen entropie toe.

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

Randgevallen en valkuilen

pageIndex is op nul gebaseerd. setLink($id, pageIndex: 2, …) verwijst naar de derde pagina. Off-by-one-fouten zijn hier de meest voorkomende vergissing.
Tekenreeks versus int bij link(). Een int is een interne bestemmings-id van addLink(). Een tekenreeks is een externe URL. Als je het verkeerde type doorgeeft, krijg je het verkeerde soort koppeling zonder foutmelding.
Koppel elke gereserveerde id. Een addLink()-id die je nooit met setLink() koppelt, heeft geen bestemming. De rechthoek is aanklikbaar maar doet niets. Koppel deze vóór save().
Het aanklikbare gebied is de rechthoek, niet de tekst. link() accepteert expliciete x, y, w, h. Maak deze groot genoeg om de zichtbare tekst te bedekken. De engine meet de glyphs niet automatisch.
Externe koppelingen worden niet gevalideerd. NextPDF slaat de URI letterlijk op. Het controleert niet of het doel oplost of veilig is. De lezer lost die op.

Prestaties

Elke koppeling of annotatie voegt één annotatiewoordenboek aan de pagina toe. De kosten zijn O(1) per element. Honderden per pagina blijven ruim binnen het budget van 2000 ms / 64 MB.

Beveiligingsnotities

Doelen van externe koppelingen worden letterlijk opgeslagen en door de lezer opgelost, niet door de bibliotheek. Behandel door gebruikers aangeleverde URL’s als niet-vertrouwd. Zet het schema op een acceptatielijst; dat is doorgaans https. Weiger javascript: en file: voordat je ze doorgeeft aan link(). Annotatietekst verschijnt in de user interface (UI) van de lezer, dus begrens de lengte van notitie-inhoud die gebruikers beheren en maak die schoon. Dit recipe voert geen invoerontleding of netwerktoegang uit.

Conformiteit

Bewering	Spec	Clausule
Een koppelingsannotatie is een hypertekstkoppeling naar een bestemming of een actie.	ISO 32000-2	§12.5.6.5
`Subtype` is `Link` voor een koppelingsannotatie.	ISO 32000-2	§12.5.6.5
De `URI` van een URI-actie is een vereiste UTF-8 ASCII-tekenreeks.	ISO 32000-2	§12.6.4.8
Een tekstannotatie is een plaknotitie (gesloten = pictogram, geopend = pop-up).	ISO 32000-2	§12.5.6.4
Expliciete bestemming `[page /XYZ left top zoom]`; null behoudt de huidige waarde.	ISO 32000-2	§12.3.2.2

Reproduceerbaarheidsprofiel — structureel. De trailer-/ID en de datum-atomen variëren bij elke save. De harness verwijdert die atomen en vergelijkt vervolgens de qpdf-genormaliseerde structuur. Dit recipe beschrijft hoe NextPDF de structuur produceert. Het doet geen algemene bewering over ISO 32000-2-conformiteit.

Commerciële context

Niet van toepassing. Koppelingen en tekstannotaties zijn Core-functies zonder Premium-grens.