Bladwijzers en een inhoudsopgave toevoegen

In een oogopslag

Dit recipe voegt bladwijzers toe als een hiërarchische documentstructuur. De PDF-lezer toont deze vermeldingen in de navigatiezijbalk, waar ze werken als aanklikbare inhoudsopgave. Een geheel getal als niveau bepaalt hoe diep het item wordt genest. Het recipe sluit aan bij examples/12-bookmarks-and-toc.php.

ISO 32000-2 noemt deze structuur de documentstructuur (document outline): een boom van structuuritems die dienstdoet als visuele inhoudsopgave.

Installatie

composer require nextpdf/core:^3

Er is geen optionele extensie vereist. De bladwijzer-API is stabiel sinds 1.0.0 en draait op de 8.1–8.4-backportmatrix.

Conceptueel overzicht

bookmark($title, $level, $y) voegt één structuuritem toe dat aan de huidige pagina is gekoppeld. De koppeling gebruikt de huidige Y-positie, tenzij je een expliciete Y-waarde meegeeft. $level bepaalt de nestingdiepte: niveau 0 is een hoofdstuk op het hoogste niveau, niveau 1 is een sectie onder het meest recente niveau-0-item, enzovoort. De engine bouwt de structuurboom voor je op. ISO 32000-2 koppelt items op elk niveau aan elkaar via Prev/Next en nestelt ze via First/Last, met de Outlines-vermelding van de catalogus als wortel.

Elk item bevat een bestemming, zodat de lezer naar de juiste pagina springt wanneer je op de bladwijzer klikt. ISO 32000-2 §12.3.2 stelt dat bestemmingen aan structuuritems mogen worden gekoppeld. Dezelfde aanroep voedt ook de inhoudsopgavebouwer van NextPDF, zodat de structuur en de weergegeven inhoudsopgave gesynchroniseerd blijven.

API-oppervlak

Het API-oppervlak wordt gegenereerd uit PHPDoc. Dit recipe maakt gebruik van één methode:

bookmark(string $title, int $level = 0, float $y = -1): static — voegt een structuuritem toe op $level dat aan de huidige pagina is gekoppeld. $y = -1 gebruikt de huidige Y-positie van de cursor. Geef een niet-negatieve Y-waarde mee om een precieze bestemming vast te leggen.

Codevoorbeeld — snelstart

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();

$doc->addPage();
$doc->bookmark('Chapter 1', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 1', newLine: true);

$doc->bookmark('Section 1.1', level: 1); // nested under Chapter 1
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Section body.');

$doc->addPage();
$doc->bookmark('Chapter 2', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 2', newLine: true);

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

Codevoorbeeld — productie

Dit volledige, harness-klare voorbeeld respecteert NEXTPDF_COOKBOOK_OUTPUT en introduceert geen eigen entropie.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('Bookmarks and Navigation');
$doc->setPrintHeader(false);
$doc->setPrintFooter(false);
$doc->setAutoPageBreak(true, margin: 25);

// Chapter 1
$doc->addPage();
$doc->bookmark('Chapter 1: Introduction', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 1: Introduction', newLine: true);
$doc->ln(3);

$doc->bookmark('What is NextPDF?', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'What is NextPDF?', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'NextPDF is a modern PDF 2.0 library for PHP 8.4+. '
    . 'It generates standards-targeting documents with typography, '
    . 'graphics, and signatures.');
$doc->ln(5);

$doc->bookmark('Key Features', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Key Features', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'HTML rendering, barcodes, PAdES signatures, '
    . 'and a worker-safe architecture.');

// Chapter 2
$doc->addPage();
$doc->bookmark('Chapter 2: Getting Started', level: 0);
$doc->setFont('helvetica', 'B', 18);
$doc->cell(0, 12, 'Chapter 2: Getting Started', newLine: true);
$doc->ln(3);

$doc->bookmark('Installation', level: 1);
$doc->setFont('helvetica', 'B', 14);
$doc->cell(0, 10, 'Installation', newLine: true);
$doc->setFont('helvetica', '', 11);
$doc->multiCell(0, 7, 'Install via Composer: composer require nextpdf/core');

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

echo "Created bookmarks.pdf with a 2-level outline\n";

Randgevallen en valkuilen

Niveausprongen. Een sprong van niveau 0 naar niveau 2 zonder niveau 1 ertussen kan in sommige lezers verkeerd worden weergegeven. Verhoog het niveau telkens met hoogstens één.
Bladwijzer vóór inhoud. Roep bookmark() aan op het punt waar je de bestemming wilt hebben. Plaats de aanroep in de meeste gevallen direct vóór de kop. Een aanroep die na de kop wordt geplaatst, zet de bestemming iets eronder.
Expliciete Y voor precieze bestemmingen. Met $y = -1 is de bestemming de huidige Y-positie van de cursor. Geef een expliciete Y-waarde mee voor een stabiele bestemming. Een expliciete Y-waarde verankert bijvoorbeeld de bovenkant van een sectie, ongeacht hoeveel inhoud eraan voorafgaat.
Ondersteuning voor de structuur is universeel, maar de presentatie verschilt. Lezers kunnen de structuur ingeklapt of uitgeklapt weergeven. Deze API kan per item geen open of gesloten status afdwingen.

Prestaties

Elke aanroep van bookmark() voegt één structuuritem en één inhoudsopgavevermelding toe, wat O(1)-werk is. De structuurboom wordt eenmaal afgerond, bij save(). Honderden bladwijzers blijven ruim binnen het budget van 2000 ms / 64 MB.

Beveiligingsnotities

Bladwijzertitels verschijnen in de navigatie-interface van de lezer. Als een titel door de gebruiker beheerde gegevens bevat, beperk dan de lengte en saneer deze zoals je dat met elke weergegeven tekenreeks zou doen. Dit recipe voert geen invoerparsing en geen netwerktoegang uit.

Conformiteit

Bewering	Specificatie	Clausule
De documentstructuur is een boom van structuuritems die fungeert als een visuele inhoudsopgave.	ISO 32000-2	§12.3.3
Structuuritems worden aan elkaar gekoppeld via `Prev`/`Next` en genest via `First`/`Last`.	ISO 32000-2	§12.3.3
Het structuurwoordenboek is de `Outlines`-vermelding van de catalogus.	ISO 32000-2	§7.7.2
Bestemmingen mogen aan structuuritems worden gekoppeld.	ISO 32000-2	§12.3.2

Reproduceerbaarheidsprofiel — structureel. De trailer-/ID en datumatomen verschillen bij elke save, dus de harness verwijdert die atomen en vergelijkt de qpdf-genormaliseerde structuur. Dit recipe beschrijft hoe NextPDF die structuur produceert. Het doet geen algemene claim van ISO 32000-2-conformiteit.

Commerciële context

Niet van toepassing. De documentstructuur en de inhoudsopgave zijn Core-functionaliteiten zonder Premium-grens.