북마크와 목차 추가하기

한눈에 보기

이 레시피에서는 흔히 북마크라고 부르는 계층적 문서 개요를 추가합니다. 리더 애플리케이션은 이러한 항목을 탐색 사이드바에 표시하며, 각 항목은 클릭 가능한 목차 역할도 합니다. 정수 레벨로 중첩을 제어합니다. 이 레시피는 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)는 현재 페이지에 바인딩된 개요 항목 하나를 추가합니다. 이 바인딩에는 현재 Y 또는 명시적 Y를 사용합니다. $level은 중첩 깊이를 설정합니다. 레벨 0은 최상위 장이고, 레벨 1은 가장 최근 레벨 0 항목 아래의 절이며, 이런 식으로 이어집니다. 엔진이 개요 트리를 대신 구성해 줍니다. ISO 32000-2는 각 레벨에서 Prev/Next로 항목을 연결하고, First/Last로 이를 중첩하며, 카탈로그의 Outlines 항목을 루트로 사용합니다.

각 항목에는 대상(destination)이 있으므로, 북마크를 클릭하면 리더가 올바른 페이지로 이동합니다. ISO 32000-2 §12.3.2는 대상이 개요 항목과 연결될 수 있다고 명시합니다. 동일한 호출이 NextPDF의 목차 빌더에도 데이터를 전달하므로, 개요와 렌더링된 목차가 동기화된 상태로 유지됩니다.

API 표면

API 표면은 PHPDoc에서 자동 생성됩니다. 이 레시피는 한 가지 메서드를 사용합니다.

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로 건너뛰면 일부 리더에서 잘못 구성된 것처럼 보이는 계층 구조가 만들어집니다. 한 번에 최대 한 단계씩만 레벨을 높이십시오.
콘텐츠 앞에 북마크 배치. 대상으로 지정하려는 지점에서 bookmark()를 호출하십시오. 대부분의 경우 이 호출을 제목 바로 앞에 배치하십시오. 제목 뒤에 배치된 호출은 대상을 제목보다 약간 아래로 설정합니다.
정확한 대상을 위한 명시적 Y. $y = -1인 경우 대상은 현재 커서 Y입니다. 안정적인 대상을 위해서는 명시적 Y를 전달하십시오. 예를 들어, 명시적 Y는 앞쪽에 콘텐츠가 얼마나 있든 관계없이 섹션의 맨 위를 고정합니다.
개요 지원은 보편적이지만 표시 방식은 다양합니다. 리더는 개요를 접힌 상태 또는 펼쳐진 상태로 렌더링할 수 있습니다. 이 API는 항목별로 열림 또는 닫힘 상태를 강제할 수 없습니다.

성능

각 bookmark() 호출은 개요 항목 하나와 목차 항목 하나를 추가하며, 이는 O(1) 작업입니다. 개요 트리는 save() 시점에 한 번만 최종 확정됩니다. 수백 개의 북마크도 2000 ms / 64 MB 예산 안에 충분히 들어갑니다.

보안 참고 사항

북마크 제목은 리더의 탐색 인터페이스에 렌더링됩니다. 사용자가 제어하는 데이터가 제목에 포함된 경우, 표시되는 다른 모든 문자열과 마찬가지로 길이를 제한하고 정제하십시오. 이 레시피는 입력 파싱이나 네트워크 액세스를 수행하지 않습니다.

적합성

설명	사양	조항
문서 개요는 시각적 TOC 역할을 하는 개요 항목 트리입니다.	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 적합성을 포괄적으로 주장하지는 않습니다.

상업적 컨텍스트

해당 없음. 문서 개요와 목차는 Premium 게이트가 적용되지 않는 Core 기능입니다.