Thêm bookmark và mục lục

Tổng quan nhanh

Công thức này thêm bookmark dưới dạng dàn ý tài liệu phân cấp. Trình đọc hiển thị các mục này trong thanh điều hướng bên; tại đó, chúng hoạt động như mục lục có thể nhấp. Một giá trị mức dạng số nguyên kiểm soát việc lồng cấp. Công thức này bám sát examples/12-bookmarks-and-toc.php.

ISO 32000-2 gọi cấu trúc này là dàn ý tài liệu: một cây gồm các mục dàn ý đóng vai trò như một mục lục trực quan.

Cài đặt

composer require nextpdf/core:^3

Không cần bất kỳ phần mở rộng tùy chọn nào. API bookmark đã ổn định từ phiên bản 1.0.0 và hoạt động trên ma trận backport 8.1–8.4.

Tổng quan khái niệm

bookmark($title, $level, $y) thêm một mục dàn ý gắn với trang hiện tại. Mục này dùng vị trí Y hiện tại làm điểm gắn, trừ khi bạn truyền vào một giá trị Y rõ ràng. $level đặt độ sâu lồng cấp: mức 0 là một chương cấp cao nhất, mức 1 là một phần nằm dưới mục cấp 0 gần nhất, và cứ thế tiếp tục. Engine sẽ tự xây dựng cây dàn ý cho bạn. ISO 32000-2 nối các mục thành chuỗi qua Prev/Next ở từng mức và lồng chúng qua First/Last, với mục Outlines của catalog làm gốc.

Mỗi mục chứa một điểm đến, vì vậy trình đọc sẽ nhảy đến đúng trang khi bạn nhấp vào bookmark. ISO 32000-2 §12.3.2 nêu rằng các điểm đến có thể được liên kết với các mục dàn ý. Cùng lệnh gọi đó cũng cung cấp dữ liệu cho bộ dựng mục lục của NextPDF, nhờ vậy dàn ý và mục lục được kết xuất luôn đồng bộ.

Bề mặt API

Bề mặt API được tạo từ PHPDoc. Công thức này dựa vào một phương thức:

bookmark(string $title, int $level = 0, float $y = -1): static — thêm một mục dàn ý ở $level và gắn với trang hiện tại. $y = -1 dùng vị trí Y hiện tại của con trỏ. Truyền vào một giá trị Y không âm để ghim một điểm đến chính xác.

Mẫu mã — bắt đầu nhanh

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

Mẫu mã — bản dùng cho sản xuất

Ví dụ hoàn chỉnh, sẵn sàng chạy trong harness này, tôn trọng NEXTPDF_COOKBOOK_OUTPUT và không tự đưa thêm entropy nào.

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

Trường hợp biên & lưu ý

Bỏ qua mức. Một bước nhảy từ mức 0 lên mức 2 mà không có mức 1 ở giữa có thể trông như lỗi định dạng trong một số trình đọc. Mỗi lần chỉ tăng mức tối đa một bậc.
Đặt bookmark trước nội dung. Gọi bookmark() tại điểm mà bạn muốn đặt điểm đến. Trong hầu hết các trường hợp, hãy đặt lệnh gọi ngay trước tiêu đề. Một lệnh gọi được đặt sau tiêu đề sẽ thiết lập điểm đến nằm hơi thấp hơn tiêu đề đó.
Giá trị Y rõ ràng cho điểm đến chính xác. Với $y = -1, điểm đến là vị trí Y hiện tại của con trỏ. Hãy truyền vào một giá trị Y rõ ràng để có điểm đến ổn định. Ví dụ, một giá trị Y rõ ràng sẽ ghim đầu của một phần bất kể có bao nhiêu nội dung đứng trước nó.
Hỗ trợ dàn ý là phổ biến, nhưng cách trình bày thì khác nhau. Các trình đọc có thể kết xuất dàn ý ở trạng thái thu gọn hoặc mở rộng. API này không thể ép từng mục ở trạng thái mở hay đóng.

Hiệu năng

Mỗi lệnh gọi bookmark() thêm một mục dàn ý và một mục trong mục lục; đây là công việc O(1). Cây dàn ý được hoàn tất một lần duy nhất, tại save(). Hàng trăm bookmark vẫn nằm gọn trong ngân sách 2000 ms / 64 MB.

Lưu ý bảo mật

Tiêu đề bookmark xuất hiện trong giao diện điều hướng của trình đọc. Nếu một tiêu đề chứa dữ liệu do người dùng kiểm soát, hãy giới hạn độ dài và làm sạch nó như mọi chuỗi hiển thị khác. Công thức này không thực hiện phân tích cú pháp đầu vào và không truy cập mạng.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản
Dàn ý tài liệu là một cây gồm các mục dàn ý đóng vai trò như một mục lục trực quan.	ISO 32000-2	§12.3.3
Các mục dàn ý nối thành chuỗi qua `Prev`/`Next` và lồng cấp qua `First`/`Last`.	ISO 32000-2	§12.3.3
Từ điển dàn ý là mục `Outlines` của catalog.	ISO 32000-2	§7.7.2
Các điểm đến có thể được liên kết với các mục dàn ý.	ISO 32000-2	§12.3.2

Hồ sơ khả năng tái lập — cấu trúc. Atom /ID trong trailer và các atom ngày tháng thay đổi sau mỗi lần lưu, vì vậy harness loại bỏ các atom đó và so sánh cấu trúc đã chuẩn hóa bằng qpdf. Công thức này mô tả cách NextPDF tạo ra cấu trúc đó. Nó không đưa ra tuyên bố bao trùm rằng tài liệu tuân thủ ISO 32000-2.

Bối cảnh thương mại

Không áp dụng. Dàn ý tài liệu và mục lục là khả năng của Core, không bị giới hạn ở Premium.