Aggiungere segnalibri e un sommario

In breve

Questa ricetta mostra come aggiungere al documento una struttura gerarchica composta da segnalibri. Il lettore PDF elenca queste voci nella barra laterale di navigazione, dove fungono anche da sommario cliccabile. Un valore intero di livello controlla l’annidamento. La ricetta segue examples/12-bookmarks-and-toc.php.

ISO 32000-2 la definisce come struttura del documento: una gerarchia ad albero di elementi della struttura che funge da sommario visivo.

Installazione

composer require nextpdf/core:^3

Non è richiesta alcuna estensione opzionale. L’API dei segnalibri è stabile dalla versione 1.0.0 e funziona con la matrice di backport 8.1–8.4.

Panoramica concettuale

bookmark($title, $level, $y) aggiunge un elemento della struttura associato alla pagina corrente. La destinazione usa la Y corrente oppure una Y esplicita. $level imposta la profondità di annidamento: il livello 0 rappresenta un capitolo di primo livello, il livello 1 una sezione sotto l’elemento di livello 0 più recente e così via. Il motore crea automaticamente l’albero della struttura. In ISO 32000-2 gli elementi sono concatenati tramite Prev/Next a ogni livello e annidati tramite First/Last, con la voce Outlines del catalogo come radice.

Ogni elemento contiene una destinazione, così il lettore passa alla pagina corretta quando si fa clic sul segnalibro. ISO 32000-2 §12.3.2 stabilisce che le destinazioni possono essere associate agli elementi della struttura. La stessa chiamata alimenta anche il generatore di sommario di NextPDF, così la struttura e il sommario renderizzato restano sincronizzati.

Superficie dell’API

La superficie dell’API è generata automaticamente da PHPDoc. Questa ricetta si basa su un solo metodo:

bookmark(string $title, int $level = 0, float $y = -1): static — aggiunge un elemento della struttura al livello $level, associato alla pagina corrente. $y = -1 utilizza la Y corrente del cursore. Passare una Y non negativa per fissare una destinazione precisa.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Questo è l’esempio completo pronto per l’harness. Rispetta NEXTPDF_COOKBOOK_OUTPUT e non introduce alcuna entropia aggiuntiva.

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

Casi limite e insidie

Salti di livello. Un salto dal livello 0 al livello 2 senza un livello 1 intermedio produce una gerarchia dall’aspetto non valido in alcuni lettori. Incrementare il livello al massimo di uno alla volta.
Inserire il segnalibro prima del contenuto. Chiamare bookmark() nel punto in cui si desidera collocare la destinazione. Nella maggior parte dei casi, collocare la chiamata subito prima del titolo. Una chiamata collocata dopo il titolo imposta la destinazione leggermente al di sotto di esso.
Y esplicita per destinazioni precise. Con $y = -1, la destinazione è la Y corrente del cursore. Passare una Y esplicita per ottenere una destinazione stabile. Ad esempio, una Y esplicita fissa l’inizio di una sezione indipendentemente dalla quantità di contenuto che la precede.
Il supporto della struttura è universale, ma la presentazione varia. I lettori possono visualizzare la struttura compressa o espansa. Questa API non può forzare uno stato aperto o chiuso per ciascun elemento.

Prestazioni

Ogni chiamata a bookmark() aggiunge un elemento della struttura e una voce del sommario, con complessità O(1). L’albero della struttura viene finalizzato una sola volta, in save(). Centinaia di segnalibri restano ampiamente entro il budget di 2000 ms / 64 MB.

Note sulla sicurezza

I titoli dei segnalibri vengono visualizzati nell’interfaccia di navigazione del lettore. Se un titolo contiene dati controllati dall’utente, limitarne la lunghezza e applicare la sanitizzazione come per qualsiasi stringa visualizzata. Questa ricetta non effettua alcun parsing dell’input né alcun accesso alla rete.

Conformità

Dichiarazione	Specifica	Clausola
La struttura del documento è un albero di elementi della struttura che funge da sommario visivo.	ISO 32000-2	§12.3.3
Gli elementi della struttura si concatenano tramite `Prev`/`Next` e si annidano tramite `First`/`Last`.	ISO 32000-2	§12.3.3
Il dizionario della struttura è la voce `Outlines` del catalogo.	ISO 32000-2	§7.7.2
Le destinazioni possono essere associate agli elementi della struttura.	ISO 32000-2	§12.3.2

Profilo di riproducibilità — strutturale. L’elemento /ID del trailer e gli elementi della data variano a ogni salvataggio; pertanto l’harness rimuove tali elementi e confronta la struttura normalizzata da qpdf. Questa ricetta descrive il modo in cui NextPDF produce tale struttura. Non costituisce una dichiarazione generale di conformità a ISO 32000-2.

Contesto commerciale

Non applicabile. La struttura del documento e il sommario sono funzionalità di Core e non richiedono alcuna licenza Premium.