ブックマークと目次を追加する

概要

このレシピでは、ブックマークと呼ばれる階層的なドキュメントアウトラインを追加します。リーダーアプリケーションでは、これらのエントリがナビゲーションサイドバーに一覧表示され、クリック可能な目次としても機能します。整数値のレベルでネストを制御します。このレシピは examples/12-bookmarks-and-toc.php に基づいています。

ISO 32000-2 では、これをドキュメントアウトラインと呼びます。これは、視覚的な目次として機能するアウトライン項目の階層ツリーです。

インストール

composer require nextpdf/core:^3

オプションの拡張機能は必要ありません。ブックマーク API は 1.0.0 以降で安定しており、8.1–8.4 のバックポートマトリックスで動作します。

概念の概要

bookmark($title, $level, $y) は、現在のページに関連付けられたアウトライン項目を 1 つ追加します。この関連付けには、現在の Y または明示的に指定した Y が使用されます。$level はネストの深さを設定します。レベル 0 は最上位の章、レベル 1 は直近のレベル 0 項目配下のセクション、というように続きます。アウトラインツリーはエンジンが構築します。ISO 32000-2 では、各レベルの項目を Prev/Next で連結し、First/Last でネストします。ルートはカタログの Outlines エントリです。

各項目には目的地が設定されているため、ブックマークをクリックするとリーダーは正しいページへジャンプします。ISO 32000-2 §12.3.2 では、目的地をアウトライン項目に関連付けられることが規定されています。同じ呼び出しは NextPDF の目次ビルダーにも渡されるため、アウトラインとレンダリングされた目次は同期された状態に保たれます。

API サーフェス

API サーフェスは PHPDoc から自動生成されます。このレシピで使用するメソッドは 1 つです。

bookmark(string $title, int $level = 0, float $y = -1): static — 現在のページに関連付けられたアウトライン項目を $level の階層に追加します。$y = -1 は現在のカーソルの Y を使用します。正確な目的地に固定するには、負でない Y を渡します。

コードサンプル — クイックスタート

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

コードサンプル — プロダクション

これは、ハーネスですぐに使える完全な例です。NEXTPDF_COOKBOOK_OUTPUT を尊重し、独自のエントロピーを一切持ち込みません。

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

エッジケースと注意点

レベルのスキップ。 間にレベル 1 を挟まずにレベル 0 からレベル 2 へジャンプすると、一部のリーダーで不正に見える階層が生成されます。レベルを増やすときは、一度に最大 1 ずつにしてください。
コンテンツの前にブックマークを設定。 目的地にしたい位置で bookmark() を呼び出します。ほとんどの場合、この呼び出しは見出しの直前に置きます。見出しの後に置くと、目的地は見出しのわずかに下に設定されます。
正確な目的地のための明示的な Y。 $y = -1 の場合、目的地は現在のカーソルの Y です。安定した目的地にするには、明示的な Y を渡します。たとえば、明示的な Y を使うと、その前にどれだけのコンテンツがあっても、セクションの先頭を固定できます。
アウトラインのサポートは普遍的ですが、表示方法は異なります。 リーダーによっては、アウトラインを折りたたんだ状態または展開した状態でレンダリングします。この API では、項目ごとに開いた状態または閉じた状態を強制できません。

パフォーマンス

各 bookmark() 呼び出しは、アウトライン項目 1 つと目次エントリ 1 つを追加します。これは O(1) の処理です。アウトラインツリーは save() 時に一度だけ確定されます。数百個のブックマークでも、2000 ms / 64 MB の予算内に十分収まります。

セキュリティに関する注意事項

ブックマークのタイトルは、リーダーのナビゲーションインターフェイスに表示されます。タイトルにユーザーが制御できるデータが含まれる場合は、表示される他の文字列と同様に、長さを制限し、サニタイズしてください。このレシピは、入力の解析もネットワークアクセスも行いません。

準拠

記述	仕様	箇条
ドキュメントアウトラインは、視覚的な目次として機能するアウトライン項目のツリーです。	ISO 32000-2	§12.3.3
アウトライン項目は `Prev`/`Next` で連結され、`First`/`Last` でネストされます。	ISO 32000-2	§12.3.3
アウトライン辞書は、カタログの `Outlines` エントリです。	ISO 32000-2	§7.7.2
目的地はアウトライン項目に関連付けられる場合があります。	ISO 32000-2	§12.3.2

再現性プロファイル — 構造的。 トレーラーの /ID と日付のアトムは保存ごとに変化するため、ハーネスはそれらのアトムを取り除き、qpdf で正規化した構造を比較します。このレシピでは、NextPDF がその構造をどのように生成するかを説明します。これは、ISO 32000-2 への準拠を包括的に主張するものではありません。

商用に関する背景

該当しません。ドキュメントアウトラインと目次は Core の機能であり、Premium のゲートはありません。