การนำทาง: คำอธิบายประกอบ ลิงก์ เค้าโครงหัวข้อ การกระทำ และไฟล์แนบ

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

โมดูล Navigation สร้างชั้นการโต้ตอบของ Portable Document Format (PDF) โมดูลนี้ครอบคลุมคำอธิบายประกอบ คำอธิบายประกอบแบบลิงก์และแบบ Uniform Resource Locator (URL) เค้าโครงหัวข้อของเอกสาร (บุ๊กมาร์ก) สารบัญ การกระทำและสายโซ่ทริกเกอร์ การเปลี่ยนหน้า และไฟล์แนบแบบฝังตัวพร้อมความสัมพันธ์ของไฟล์ที่เกี่ยวข้อง

การติดตั้ง

composer require nextpdf/core:^3

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

ISO 32000-2 §12 กำหนดคุณสมบัติเชิงโต้ตอบของเอกสาร PDF ได้แก่ คำอธิบายประกอบ การกระทำ ปลายทาง และเค้าโครงหัวข้อของเอกสาร โมดูลนี้เข้ารหัสชั้นดังกล่าวให้เอนจิน คลาส manager รวบรวมเจตนา ส่วน value object ส่งต่อข้อมูลที่ manager เหล่านั้นปล่อยออกมา

AnnotationManager คือจุดเริ่มต้นที่ครอบคลุมที่สุด คลาสนี้เพิ่มคำอธิบายประกอบแบบข้อความ free-text เส้น สี่เหลี่ยมจัตุรัส วงกลม รูปหลายเหลี่ยม เส้นหลายส่วน ลายมือ และแบบ text-markup (ไฮไลต์และขีดเส้นใต้) คลาสนี้ถูกเสริมความแข็งแกร่งเพื่อรับมืออินพุตที่เป็นภัย: ชนิดย่อยของคำอธิบายประกอบที่ไม่รู้จักจะใช้ค่าเริ่มต้นที่ปลอดภัย ชื่อไอคอนที่ไม่ใช่โทเคนชื่อ PDF ที่ถูกต้องจะถูกแทนที่ และ QuadPoints ของ text-markup ต้องอยู่ในรูปจำนวน float ที่เป็นพหุคูณของแปด มิฉะนั้นจะถูกตัดทิ้ง การตรวจสอบเหล่านี้คือการป้องกันการแทรก PDF (PDF-injection) ไม่ใช่เพียงความสะดวกในการตรวจสอบความถูกต้อง LinkManager จัดการลิงก์ภายใน ปลายทางแบบมีชื่อ และคำอธิบายประกอบ URL คลาสนี้จองอ็อบเจกต์คำอธิบายประกอบล่วงหน้าเพื่อให้ Writer สามารถอ้างอิงอ็อบเจกต์เหล่านั้นได้ก่อนการ serialize

BookmarkManager และ TocBuilder สร้างลำดับชั้นการนำทาง เค้าโครงหัวข้อของเอกสารคือต้นไม้บุ๊กมาร์กที่โปรแกรมดูแสดงในแถบด้านข้าง TocBuilder เรนเดอร์สารบัญบนหน้า และสามารถใช้ FontMetrics สำหรับการจัดวางแบบ leader/width ส่วน OutlineAutoGenerator สร้างเค้าโครงหัวข้อจากโครงสร้างของเอกสาร

ลำดับชั้น Action ภายใต้ NextPDF\Navigation\Action จำลองพฤติกรรมที่ขับเคลื่อนด้วยทริกเกอร์ ได้แก่ GoTo (แบบรีโมตและแบบฝังตัว) launch named hide reset/submit form และการตั้งค่าสถานะ optional-content การกระทำ rendition ของ screen-annotation ตาม §13 ถูกเลื่อนออกไปเป็นงานในอนาคตและยังไม่ได้เชื่อมต่อ อย่าพึ่งพาการกระทำดังกล่าวในฐานะการกระทำที่รองรับ Action::withNext() สร้างสายโซ่การกระทำที่ทำงานกับเหตุการณ์ทริกเกอร์เดียว PageTransition จำลองการเปลี่ยนหน้าแบบงานนำเสนอ FileAttachment ฝังไฟล์จากพาธหรือจากสตริงไบต์ และติดป้ายกำกับด้วย AFRelationship (enum ความสัมพันธ์ของไฟล์ที่เกี่ยวข้อง) คลาสนี้คืนค่า FileAttachmentResult และเขียนผ่าน writeAttachments() manager หลักคือ @since 1.0.0 ลำดับชั้นการกระทำคือ @since 2.1.0 คอนสตรักเตอร์ FileAttachment และ AFRelationship เริ่มมีใน @since 1.8.0 / @since 1.1.0

พื้นผิว API

คลาส	สมาชิกสำคัญ	บทบาท
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	ตัวสร้างคำอธิบายประกอบที่มีอินพุตปลอดภัยจากการแทรก (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	ลิงก์ภายใน ปลายทางแบบมีชื่อ คำอธิบายประกอบ URL (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	ต้นไม้เค้าโครงหัวข้อของเอกสาร (บุ๊กมาร์ก) (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	สารบัญบนหน้า (@since 1.0.0)
Action (อินเทอร์เฟซ)	subtype(), toDictionary(), withNext(), nextChain()	การกระทำที่ถูกทริกเกอร์ + สายโซ่การกระทำ (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	การเปลี่ยนหน้าแบบงานนำเสนอ (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	ไฟล์แนบแบบฝังตัว (@since 1.0.0)
AFRelationship (enum)	toPdfName()	ความสัมพันธ์ของไฟล์ที่เกี่ยวข้อง (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	ชุดแฟล็กคำอธิบายประกอบที่เปลี่ยนแปลงไม่ได้ (@since 1.2.0)

รัน composer docs:generate-api-php -- --module=Navigation เพื่อสร้างตาราง PHPDoc ฉบับเต็ม

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

examples/12-bookmarks-and-toc.php สร้างเค้าโครงหัวข้อของเอกสารผ่าน facade ระดับสูงที่ห่อหุ้ม BookmarkManager หากต้องการใช้ manager โดยตรง ให้ใช้รูปแบบนี้:

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Navigation\BookmarkManager;

$bookmarks = new BookmarkManager();
$bookmarks->addBookmark(title: 'Chapter 1', level: 0, pageIndex: 0);
$bookmarks->addBookmark(title: '1.1 Overview', level: 1, pageIndex: 0);
$bookmarks->addBookmark(title: 'Chapter 2', level: 0, pageIndex: 4);

if ($bookmarks->hasBookmarks()) {
    // The Writer calls $bookmarks->write(...) during catalog serialization.
}

ตัวอย่างโค้ด — การใช้งานจริง

ฝังไฟล์แนบพร้อมระบุความสัมพันธ์ของไฟล์ที่เกี่ยวข้องอย่างชัดเจน จากนั้นตรวจสอบผลลัพธ์ก่อนสรุปการสร้างเอกสารขั้นสุดท้าย

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Navigation\AFRelationship;
use NextPDF\Navigation\FileAttachment;

$attachments = new FileAttachment();

$attachments->embedFile(
    path: '/srv/invoices/INV-2026-0042.xml',
    description: 'Structured invoice source (Factur-X)',
    afRelationship: AFRelationship::Source,
);

if ($attachments->hasAttachments()) {
    // writeAttachments() is invoked by the Writer with a live ObjectRegistry;
    // getCount() lets the application assert the expected attachment count.
    assert($attachments->getCount() === 1);
}

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

• AnnotationManager ปรับอินพุตที่เป็นภัยให้เป็นมาตรฐานโดยไม่แจ้งเตือน: ชนิดย่อยที่ไม่ถูกต้องจะกลายเป็นค่าเริ่มต้น ไอคอนที่ไม่ใช่ชื่อจะกลายเป็นไอคอนค่าเริ่มต้น และ QuadPoints ที่ผิดรูปจะถูกตัดทิ้ง คำอธิบายประกอบยังคงถูกสร้างขึ้น ให้ตรวจสอบความถูกต้องของอินพุตตั้งแต่ต้นทางหากต้องการใช้ค่าที่ระบุอย่างแม่นยำ
• LinkManager::preallocateAnnotationObjects() ต้องทำงานก่อนที่ Writer จะ serialize การอ้างอิง มิฉะนั้นปลายทางของลิงก์จะ resolve เป็นค่าว่าง
• Action::withNext() คืนค่าการกระทำใหม่ที่มีสายโซ่ติดมาด้วย อินเทอร์เฟซรองรับการต่อสายโซ่แบบเปลี่ยนแปลงไม่ได้ ไม่ใช่การปรับเปลี่ยนในที่
• FileAttachment::writeAttachments() จำเป็นต้องมี ObjectRegistry ที่ใช้งานอยู่จาก Writer เมื่อเรียกใช้แบบแยกเดี่ยว manager จะสะสมเจตนาไว้แต่จะไม่เขียนสิ่งใดจนกว่า Writer จะขับเคลื่อน
• AnnotationFlags คือชุดแฟล็กที่เปลี่ยนแปลงไม่ได้ with()/without() คืนค่าอินสแตนซ์ใหม่ ส่วนอินสแตนซ์เดิมไม่เปลี่ยนแปลง

ประสิทธิภาพ

การสะสมคำอธิบายประกอบ ลิงก์ และบุ๊กมาร์กเป็นแบบ O(n) ตามจำนวนรายการ และไม่มีการ reflow ต้นทุนของไฟล์แนบแบบฝังตัวถูกกำหนดโดยขนาดไบต์ที่ฝัง ไม่ใช่ภาระงานของ manager เวิร์กโหลดอ้างอิงค่าเริ่มต้นอยู่ภายในงบประมาณ 1500 ms wall / 64 MB peak โปรไฟล์การทำซ้ำได้คือ structural: หมายเลขอ็อบเจกต์และ /ID ในเทรลเลอร์จะแตกต่างกันในแต่ละรอบการทำงาน เอกสารสองฉบับที่มีเจตนาการนำทางเดียวกันจะเท่าเทียมกันเชิงโครงสร้างแต่ไม่เหมือนกันในระดับไบต์

หมายเหตุด้านความปลอดภัย

AnnotationManager ปฏิบัติต่อชนิดย่อยของคำอธิบายประกอบ ไอคอน และ QuadPoints เสมือนเป็นข้อมูลที่ไม่น่าเชื่อถือ คลาสนี้ตรวจสอบความถูกต้องของแต่ละค่าเทียบกับ allow-list หรือรูปแบบ และแทนที่ค่าที่ไม่ถูกต้องแทนที่จะเขียนค่านั้นผ่านไป การกระทำนี้ปิดช่องทางการแทรกชื่อ PDF (PDF name-injection) LinkManager::addUrlAnnotation() เข้ารหัส URL ลงในการกระทำแบบลิงก์ URL ยังคงเป็นขอบเขตความเชื่อถือของผู้บริโภค: URL ที่เป็นภัยยังอาจเป็น URL ที่ถูกต้องได้ ดังนั้นจึงควรล้างปลายทางให้สะอาดก่อนเพิ่ม FileAttachment ฝังไบต์ตามอำเภอใจ จำกัดขนาดที่ฝัง และปฏิบัติต่อแหล่งไฟล์แนบที่ผู้ใช้จัดหามาให้เสมือนเป็นข้อมูลที่ไม่น่าเชื่อถือ ดูแบบจำลองภัยคุกคามของเอนจินได้ที่ /modules/core/security/

ความสอดคล้อง

โครงสร้างที่โมดูลนี้ปล่อยออกมาเป็นไปตาม ISO 32000-2 §12 สำหรับคำอธิบายประกอบ การกระทำ ปลายทาง และลำดับชั้นเค้าโครงหัวข้อของเอกสาร การอ้างอิงข้อกำหนดรายคุณสมบัติ (ไอคอนคำอธิบายประกอบ §12.5.6.4 QuadPoints ของ text-markup §12.5.6.10 การกระทำ §12.6) ถูกบันทึกไว้แบบอินไลน์ใน src/Navigation/ และทดสอบโดย tests/Unit/Navigation/ สิ่งเหล่านี้คือข้อเท็จจริงเชิงการนำไปใช้ ไม่ใช่คำแถลงความสอดคล้อง PDF 2.0 แบบครบวงจร ความสอดคล้องของเอกสารทั้งฉบับได้รับการตรวจสอบโดยชุด oracle และ golden ที่อธิบายไว้ใน /modules/core/conformance/

ดูเพิ่มเติม

• โมดูล Document
• โมดูล Multimedia — อ็อบเจกต์ rendition ที่การกระทำ rendition เล่น
• โมดูล Writer — serialize โครงสร้างการนำทาง
• ภาพรวมความสอดคล้อง
• แบบจำลองความปลอดภัยของเอนจิน