เพิ่มบุ๊กมาร์กและสารบัญ

ภาพรวมโดยย่อ

สูตรนี้เพิ่มบุ๊กมาร์กในรูปแบบเค้าโครงเอกสารแบบลำดับชั้น แอปอ่านเอกสารจะแสดงรายการเหล่านี้ในแถบนำทางด้านข้างให้ทำหน้าที่เป็นสารบัญที่คลิกได้ ระดับจำนวนเต็มจะกำหนดชั้นการซ้อน สูตรนี้อิงจากไฟล์ examples/12-bookmarks-and-toc.php เป็นหลัก

ISO 32000-2 เรียกโครงสร้างนี้ว่าเค้าโครงเอกสาร ซึ่งเป็นแผนผังต้นไม้ของรายการเค้าโครงที่ทำหน้าที่เป็นสารบัญเชิงภาพ

การติดตั้ง

composer require nextpdf/core:^3

ไม่จำเป็นต้องใช้ส่วนขยายเพิ่มเติมใด ๆ bookmark API มีความเสถียรมาตั้งแต่เวอร์ชัน 1.0.0 และทำงานได้บนเมทริกซ์ backport 8.1–8.4

ภาพรวมเชิงแนวคิด

bookmark($title, $level, $y) เพิ่มรายการเค้าโครงหนึ่งรายการที่ผูกกับหน้าปัจจุบัน การผูกนี้ใช้ตำแหน่ง Y ปัจจุบัน เว้นแต่คุณจะส่งค่า Y ที่ระบุอย่างชัดเจน $level กำหนดความลึกของการซ้อนชั้น โดยระดับ 0 คือบทระดับบนสุด ระดับ 1 คือส่วนภายใต้รายการระดับ 0 ล่าสุด และดำเนินต่อไปในลักษณะเดียวกัน เอนจินจะสร้างแผนผังต้นไม้ของเค้าโครงให้โดยอัตโนมัติ ISO 32000-2 เชื่อมโยงรายการในแต่ละระดับเข้าด้วยกันผ่าน Prev/Next และซ้อนชั้นรายการผ่าน First/Last โดยมีรายการ Outlines ของแคทาล็อกเป็นรากของแผนผัง

แต่ละรายการมีปลายทางกำกับไว้ ดังนั้นโปรแกรมอ่านจะข้ามไปยังหน้าที่ถูกต้องเมื่อคุณคลิกบุ๊กมาร์ก 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";

กรณีขอบและข้อควรระวัง

การข้ามระดับ การกระโดดจากระดับ 0 ไปยังระดับ 2 โดยไม่มีระดับ 1 คั่นกลางอาจทำให้โครงสร้างดูผิดรูปแบบในโปรแกรมอ่านบางตัว เพิ่มระดับครั้งละไม่เกินหนึ่งระดับ
บุ๊กมาร์กก่อนเนื้อหา เรียก bookmark() ณ จุดที่คุณต้องการให้เป็นปลายทาง ในกรณีส่วนใหญ่ ให้วางการเรียกไว้ก่อนหัวข้อทันที การเรียกที่วางไว้หลังหัวข้อจะตั้งปลายทางให้อยู่ต่ำกว่าหัวข้อเล็กน้อย
ระบุค่า Y อย่างชัดเจนเพื่อให้ปลายทางแม่นยำ เมื่อใช้ $y = -1 ปลายทางจะเป็นตำแหน่ง Y ของเคอร์เซอร์ปัจจุบัน ส่งค่า Y ที่ระบุอย่างชัดเจนเพื่อให้ได้ปลายทางคงที่ ตัวอย่างเช่น ค่า Y ที่ระบุอย่างชัดเจนจะตรึงตำแหน่งด้านบนสุดของส่วนนั้นไว้ ไม่ว่าจะมีเนื้อหานำหน้ามากเพียงใดก็ตาม
เค้าโครงได้รับการรองรับอย่างเป็นสากล แต่การแสดงผลแตกต่างกัน โปรแกรมอ่านอาจเรนเดอร์เค้าโครงในสถานะยุบหรือขยายก็ได้ API นี้ไม่สามารถบังคับสถานะเปิดหรือปิดในแต่ละรายการได้

ประสิทธิภาพ

การเรียก bookmark() แต่ละครั้งเพิ่มรายการเค้าโครงหนึ่งรายการและรายการสารบัญหนึ่งรายการ ซึ่งเป็นงานระดับ 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 ของ trailer และอะตอมวันที่จะเปลี่ยนแปลงทุกครั้งที่บันทึก ดังนั้นชุดทดสอบจึงตัดอะตอมเหล่านั้นออก แล้วเปรียบเทียบโครงสร้างที่ปรับให้อยู่ในรูปมาตรฐานด้วย qpdf สูตรนี้อธิบายวิธีที่ NextPDF สร้างโครงสร้างดังกล่าว สูตรนี้ไม่ได้ยืนยันความสอดคล้องตาม ISO 32000-2 แบบครอบคลุมทั้งหมด

บริบทเชิงพาณิชย์

ไม่เกี่ยวข้อง เค้าโครงเอกสารและสารบัญเป็นความสามารถของ Core และไม่มีการจำกัดสิทธิ์แบบ Premium