Yer imleri ve içindekiler tablosu eklemek

Bir bakışta

Bu tarifte yer imleri, hiyerarşik bir belge ana hattı olarak eklenir. Okuyucu uygulaması bu girdileri gezinme kenar çubuğunda gösterir; burada tıklanabilir bir içindekiler tablosu görevi görürler. İç içe yerleşimi bir tamsayı düzeyi belirler. Bu tarif, examples/12-bookmarks-and-toc.php dosyasını temel alır.

ISO 32000-2, bu yapıyı belge ana hattı olarak adlandırır: görsel bir içindekiler tablosu işlevi gören ana hat öğeleri ağacı.

Kurulum

composer require nextpdf/core:^3

Herhangi bir isteğe bağlı uzantı gerekmez. Yer imi API’si 1.0.0 sürümünden bu yana kararlıdır ve 8.1–8.4 geri taşıma matrisi kapsamında çalışır.

Kavramsal genel bakış

bookmark($title, $level, $y), geçerli sayfaya bağlı bir ana hat öğesi ekler. Açık bir Y değeri geçirmediğiniz sürece hedef, geçerli Y konumunu kullanır. $level iç içe yerleşim derinliğini belirler: düzey 0 üst düzey bir bölümdür, düzey 1 ise en son düzey-0 öğesinin altında bir alt bölümdür ve bu böyle devam eder. Ana hat ağacını sizin yerinize altyapı oluşturur. ISO 32000-2, öğeleri her düzeyde Prev/Next aracılığıyla zincirler ve First/Last aracılığıyla iç içe yerleştirir; kök olarak da kataloğun Outlines girdisini kullanır.

Her öğe bir hedef taşır; böylece yer imine tıkladığınızda okuyucu doğru sayfaya atlar. ISO 32000-2 §12.3.2, hedeflerin ana hat öğeleriyle ilişkilendirilebileceğini belirtir. Aynı çağrı NextPDF’in içindekiler tablosu oluşturucusunu da besler; böylece ana hat ile üretilen içindekiler tablosu eşzamanlı kalır.

API yüzeyi

API yüzeyi PHPDoc’tan üretilir. Bu tarif tek bir yönteme dayanır:

bookmark(string $title, int $level = 0, float $y = -1): static — geçerli sayfaya bağlı, $level düzeyinde bir ana hat öğesi ekler. $y = -1 geçerli imleç Y konumunu kullanır. Kesin bir hedef sabitlemek için negatif olmayan bir Y değeri geçirin.

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

Bu eksiksiz ve koşum takımına hazır örnek, NEXTPDF_COOKBOOK_OUTPUT değişkenine uyar ve kendiliğinden herhangi bir rastgelelik eklemez.

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

Sınır durumları ve tuzaklar

Düzey atlamaları. Düzey 0’dan, aradaki düzey 1 olmadan düzey 2’ye atlamak bazı okuyucularda hatalı biçimlendirilmiş görünebilir. Düzeyi her seferinde en çok bir artırın.
İçerikten önce yer imi. Hedefin olmasını istediğiniz noktada bookmark() yöntemini çağırın. Çoğu durumda çağrıyı başlığın hemen öncesine yerleştirin. Başlıktan sonra yerleştirilen bir çağrı, hedefi başlığın biraz altına ayarlar.
Tam hedefler için açık Y. $y = -1 ile hedef, geçerli imleç Y konumudur. Kararlı bir hedef için açık bir Y değeri geçirin. Örneğin açık bir Y değeri, kendisinden önce ne kadar içerik bulunduğundan bağımsız olarak bir bölümün üst noktasını sabitler.
Ana hat desteği evrenseldir, ancak sunum değişkenlik gösterir. Okuyucular ana hattı daraltılmış veya genişletilmiş olarak gösterebilir. Bu API, öğe başına açık ya da kapalı durumu zorunlu kılamaz.

Performans

Her bookmark() çağrısı bir ana hat öğesi ve bir içindekiler tablosu girdisi ekler; bu da O(1) işlemdir. Ana hat ağacı bir kez, save() sırasında sonlandırılır. Yüzlerce yer imi, 2000 ms / 64 MB bütçesinin oldukça altında kalır.

Güvenlik notları

Yer imi başlıkları okuyucunun gezinme arayüzünde görünür. Bir başlık kullanıcı denetimindeki veriler içeriyorsa, uzunluğunu sınırlayın ve görüntülenen herhangi bir dizgeyi temizlediğiniz gibi temizleyin. Bu tarif girdi ayrıştırması yapmaz ve ağ erişimi gerçekleştirmez.

Uygunluk

İfade	Belirtim	Madde
Belge ana hattı, görsel bir içindekiler tablosu işlevi gören bir ana hat öğeleri ağacıdır.	ISO 32000-2	§12.3.3
Ana hat öğeleri `Prev`/`Next` aracılığıyla zincirlenir ve `First`/`Last` aracılığıyla iç içe yerleştirilir.	ISO 32000-2	§12.3.3
Ana hat sözlüğü, kataloğun `Outlines` girdisidir.	ISO 32000-2	§7.7.2
Hedefler ana hat öğeleriyle ilişkilendirilebilir.	ISO 32000-2	§12.3.2

Yeniden üretilebilirlik profili — yapısal. Treyler /ID ve tarih atomları her kaydetme işleminde değişir; bu nedenle koşum takımı bu atomları çıkarır ve qpdf ile normalleştirilmiş yapıyı karşılaştırır. Bu tarif, NextPDF’in bu yapıyı nasıl ürettiğini açıklar. ISO 32000-2’ye uygunluk konusunda genel bir iddiada bulunmaz.

Ticari bağlam

Uygulanmaz. Belge ana hattı ve içindekiler tablosu, Premium kısıtlaması bulunmayan Core yetenekleridir.