Menambahkan markah dan daftar isi

Sekilas pandang

Resep ini menambahkan markah sebagai kerangka dokumen hierarkis. Aplikasi pembaca menampilkan entri ini di bilah sisi navigasi, sehingga entri tersebut berfungsi sebagai daftar isi yang dapat diklik. Nilai tingkat berupa bilangan bulat mengontrol susunan bertingkat. Resep ini mengikuti examples/12-bookmarks-and-toc.php.

ISO 32000-2 menyebut struktur ini sebagai kerangka dokumen: pohon item kerangka yang berfungsi sebagai daftar isi visual.

Instalasi

composer require nextpdf/core:^3

Tidak diperlukan ekstensi opsional. API markah stabil sejak 1.0.0 dan berjalan pada matriks backport 8.1–8.4.

Tinjauan konseptual

bookmark($title, $level, $y) menambahkan satu item kerangka yang dikaitkan dengan halaman saat ini. Kaitannya menggunakan posisi Y saat ini, kecuali jika Anda memberikan nilai Y secara eksplisit. $level menetapkan kedalaman susunan bertingkat: tingkat 0 adalah bab tingkat teratas, tingkat 1 adalah bagian di bawah item tingkat 0 terbaru, dan seterusnya. Mesin membangun pohon kerangka untuk Anda. ISO 32000-2 merangkai item melalui Prev/Next pada setiap tingkat dan menyusunnya secara bertingkat melalui First/Last, dengan entri Outlines pada katalog sebagai akar.

Setiap item membawa tujuan, sehingga pembaca langsung menuju halaman yang tepat saat Anda mengeklik markah tersebut. ISO 32000-2 §12.3.2 menyatakan bahwa tujuan dapat dikaitkan dengan item kerangka. Panggilan yang sama juga menjadi masukan bagi pembangun daftar isi NextPDF, sehingga kerangka dan daftar isi yang dirender tetap selaras.

Permukaan API

Permukaan API dihasilkan dari PHPDoc. Resep ini menggunakan satu metode:

bookmark(string $title, int $level = 0, float $y = -1): static — menambahkan item kerangka pada $level yang dikaitkan dengan halaman saat ini. $y = -1 menggunakan posisi Y kursor saat ini. Berikan nilai Y nonnegatif untuk menyematkan tujuan secara presisi.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Contoh lengkap yang siap digunakan oleh harness ini menghormati NEXTPDF_COOKBOOK_OUTPUT dan tidak menambahkan entropi sendiri.

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

Kasus tepi & jebakan

Lompatan tingkat. Lompatan dari tingkat 0 ke tingkat 2 tanpa tingkat 1 di antaranya dapat tampak tidak terbentuk dengan benar pada sebagian pembaca. Naikkan tingkat paling banyak satu pada setiap langkah.
Markah sebelum konten. Panggil bookmark() pada titik tempat Anda menginginkan tujuannya. Pada sebagian besar kasus, tempatkan panggilan tersebut tepat sebelum judul. Panggilan yang ditempatkan setelah judul menetapkan tujuan sedikit di bawahnya.
Y eksplisit untuk tujuan yang presisi. Dengan $y = -1, tujuan memakai posisi Y kursor saat ini. Berikan nilai Y secara eksplisit untuk tujuan yang stabil. Misalnya, nilai Y eksplisit menyematkan bagian atas sebuah bagian tanpa bergantung pada seberapa banyak konten yang mendahuluinya.
Dukungan kerangka bersifat universal, tetapi penyajiannya bervariasi. Pembaca dapat merender kerangka dalam keadaan terlipat atau terbentang. API ini tidak dapat memaksakan keadaan terbuka atau tertutup untuk tiap item.

Kinerja

Setiap panggilan bookmark() menambahkan satu item kerangka dan satu entri daftar isi, yang merupakan operasi O(1). Pohon kerangka difinalkan sekali, pada save(). Ratusan markah tetap jauh di bawah anggaran 2000 ms / 64 MB.

Catatan keamanan

Judul markah muncul di antarmuka navigasi pembaca. Jika judul memuat data yang dikendalikan pengguna, batasi panjangnya dan bersihkan seperti string lain yang akan ditampilkan. Resep ini tidak mengurai masukan dan tidak mengakses jaringan.

Kesesuaian

Pernyataan	Spesifikasi	Klausa
Kerangka dokumen adalah pohon item kerangka yang berperan sebagai daftar isi visual.	ISO 32000-2	§12.3.3
Item kerangka dirangkai melalui `Prev`/`Next` dan disusun bertingkat melalui `First`/`Last`.	ISO 32000-2	§12.3.3
Kamus kerangka adalah entri `Outlines` pada katalog.	ISO 32000-2	§7.7.2
Tujuan dapat dikaitkan dengan item kerangka.	ISO 32000-2	§12.3.2

Profil reproduktibilitas — struktural. Atom /ID dan tanggal pada trailer berubah pada setiap penyimpanan, sehingga harness menghapus atom-atom tersebut dan membandingkan struktur yang dinormalkan oleh qpdf. Resep ini menjelaskan cara NextPDF menghasilkan struktur tersebut. Resep ini tidak menyatakan kesesuaian ISO 32000-2 sebagai klaim menyeluruh.

Konteks komersial

Tidak berlaku. Kerangka dokumen dan daftar isi adalah kemampuan Core tanpa batasan Premium.