Dodawanie zakładek i spisu treści

W skrócie

Ten przepis dodaje zakładki jako hierarchiczny konspekt dokumentu. Czytnik wyświetla te pozycje w bocznym panelu nawigacji, gdzie działają jako klikalny spis treści. O zagnieżdżeniu decyduje poziom będący liczbą całkowitą. Przepis bazuje na examples/12-bookmarks-and-toc.php.

Norma ISO 32000-2 określa tę strukturę jako konspekt dokumentu: drzewo pozycji konspektu pełniące funkcję wizualnego spisu treści.

Instalacja

composer require nextpdf/core:^3

Nie wymaga to żadnego opcjonalnego rozszerzenia. API zakładek jest stabilne od wersji 1.0.0 i działa w ramach macierzy backportów 8.1–8.4.

Przegląd koncepcyjny

bookmark($title, $level, $y) dodaje pojedynczą pozycję konspektu powiązaną z bieżącą stroną. Powiązanie używa bieżącej pozycji Y, chyba że przekażesz jawną wartość Y. $level określa głębokość zagnieżdżenia: poziom 0 oznacza rozdział najwyższego poziomu, poziom 1 oznacza sekcję w obrębie ostatniej pozycji poziomu 0 i tak dalej. Silnik zbuduje za Ciebie drzewo konspektu. Norma ISO 32000-2 łączy pozycje w łańcuch za pomocą Prev/Next na każdym poziomie i zagnieżdża je za pomocą First/Last, przy czym korzeniem jest pozycja Outlines w katalogu.

Każda pozycja zawiera miejsce docelowe, dzięki czemu po kliknięciu zakładki czytnik przechodzi do właściwej strony. Norma ISO 32000-2 §12.3.2 stanowi, że miejsca docelowe mogą być powiązane z pozycjami konspektu. To samo wywołanie dostarcza też danych do generatora spisu treści w NextPDF, dzięki czemu konspekt i wyrenderowany spis treści pozostają zsynchronizowane.

Powierzchnia API

Powierzchnia API jest generowana z PHPDoc. Ten przepis korzysta z jednej metody:

bookmark(string $title, int $level = 0, float $y = -1): static — dodaje pozycję konspektu na poziomie $level, powiązaną z bieżącą stroną. Przy $y = -1 używana jest bieżąca pozycja Y kursora. Przekaż nieujemną wartość Y, aby dokładnie przypiąć miejsce docelowe.

Przykładowy kod — szybki start

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

Przykładowy kod — produkcja

Ten kompletny przykład, gotowy do uruchomienia w środowisku testowym, respektuje NEXTPDF_COOKBOOK_OUTPUT i sam nie wprowadza żadnej entropii.

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

Przypadki brzegowe i pułapki

Pomijanie poziomów. Przeskok z poziomu 0 do poziomu 2 bez poziomu 1 po drodze może w niektórych czytnikach wyglądać na uszkodzony. Zwiększaj poziom o najwyżej jeden naraz.
Zakładka przed treścią. Wywołaj bookmark() dokładnie tam, gdzie ma wskazywać miejsce docelowe. W większości przypadków umieść wywołanie bezpośrednio przed nagłówkiem. Wywołanie umieszczone po nagłówku ustawia miejsce docelowe nieco poniżej niego.
Jawna wartość Y dla precyzyjnych miejsc docelowych. Przy $y = -1 miejscem docelowym jest bieżąca pozycja Y kursora. Aby uzyskać stabilne miejsce docelowe, przekaż jawną wartość Y. Na przykład jawna wartość Y przypina górę sekcji niezależnie od tego, ile treści ją poprzedza.
Obsługa konspektu jest powszechna, ale sposób prezentacji może się różnić. Czytniki mogą wyświetlać konspekt zwinięty lub rozwinięty. To API nie może wymusić stanu otwartego ani zamkniętego dla poszczególnych pozycji.

Wydajność

Każde wywołanie bookmark() dołącza jedną pozycję konspektu i jedną pozycję spisu treści; jest to operacja o złożoności O(1). Drzewo konspektu jest finalizowane tylko raz, podczas save(). Setki zakładek mieszczą się z dużym zapasem w budżecie 2000 ms / 64 MB.

Uwagi dotyczące bezpieczeństwa

Tytuły zakładek są widoczne w interfejsie nawigacji czytnika. Jeśli tytuł zawiera dane kontrolowane przez użytkownika, ogranicz jego długość i oczyść go tak jak każdy inny wyświetlany ciąg znaków. Ten przepis nie parsuje danych wejściowych ani nie uzyskuje dostępu do sieci.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula
Konspekt dokumentu jest drzewem pozycji konspektu pełniącym funkcję wizualnego spisu treści.	ISO 32000-2	§12.3.3
Pozycje konspektu są łączone w łańcuch za pomocą `Prev`/`Next` i zagnieżdżane za pomocą `First`/`Last`.	ISO 32000-2	§12.3.3
Słownik konspektu jest pozycją `Outlines` w katalogu.	ISO 32000-2	§7.7.2
Miejsca docelowe mogą być powiązane z pozycjami konspektu.	ISO 32000-2	§12.3.2

Profil odtwarzalności — strukturalny. Atomy /ID w zwiastunie oraz atomy daty zmieniają się przy każdym zapisie, dlatego środowisko testowe usuwa je i porównuje strukturę znormalizowaną przez qpdf. Ten przepis opisuje, w jaki sposób NextPDF wytwarza tę strukturę. Nie deklaruje zgodności z ISO 32000-2 jako ogólnego stwierdzenia.

Kontekst komercyjny

Nie dotyczy. Konspekt dokumentu i spis treści są funkcjami Core bez bramki Premium.