Điều hướng: chú thích, liên kết, đại cương, hành động và tệp đính kèm

Tổng quan nhanh

Mô-đun Navigation xây dựng lớp tương tác của Portable Document Format (PDF). Lớp này bao gồm chú thích, chú thích liên kết và Uniform Resource Locator (URL), đại cương tài liệu (bookmark), mục lục, hành động và chuỗi kích hoạt, chuyển trang, cùng các tệp nhúng với quan hệ tệp liên kết tương ứng.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

ISO 32000-2 §12 định nghĩa các tính năng tương tác của một tài liệu PDF: chú thích, hành động, điểm đến và đại cương tài liệu. Mô-đun này mã hóa lớp đó cho engine. Các lớp manager thu thập ý định; các value object mang dữ liệu do các manager đó phát ra.

AnnotationManager là điểm vào bao quát nhất. Lớp này thêm các chú thích text, free-text, line, square, circle, polygon, polyline, ink và text-markup (highlight và underline). Lớp này được gia cố để chống đầu vào độc hại: một subtype chú thích không xác định sẽ được đưa về mặc định an toàn, một tên icon không phải PDF name token hợp lệ sẽ được thay thế, và QuadPoints của text-markup phải được truyền vào dưới dạng bội số của tám số thực, nếu không sẽ bị bỏ qua. Những kiểm tra này là biện pháp phòng thủ chống PDF-injection, không nhằm thay thế việc xác thực đầu vào. LinkManager xử lý liên kết nội bộ, điểm đến có tên và chú thích URL. Lớp này cấp phát trước các đối tượng chú thích để Writer có thể tham chiếu chúng trước khi tuần tự hóa.

BookmarkManager và TocBuilder xây dựng cây phân cấp điều hướng. Đại cương tài liệu là cây bookmark mà trình xem hiển thị trong thanh bên. TocBuilder kết xuất mục lục ngay trên trang và có thể dùng FontMetrics cho bố cục leader/width. OutlineAutoGenerator suy ra đại cương từ cấu trúc tài liệu.

Hệ phân cấp Action dưới NextPDF\Navigation\Action mô hình hóa hành vi được kích hoạt theo trigger: GoTo (từ xa và nhúng), launch, named, hide, form reset/submit và đặt trạng thái optional-content. Hành động rendition cho chú thích màn hình ở §13 được hoãn lại; đây là công việc trong tương lai và chưa được kết nối. Đừng dựa vào nó như một hành động được hỗ trợ. Action::withNext() xây dựng chuỗi hành động chạy cho một sự kiện trigger duy nhất. PageTransition mô hình hóa hiệu ứng chuyển trang trình chiếu. FileAttachment nhúng một tệp từ đường dẫn hoặc từ chuỗi byte, rồi gắn nhãn cho tệp đó bằng một AFRelationship (enum quan hệ tệp liên kết). Nó trả về một FileAttachmentResult và ghi thông qua writeAttachments(). Các manager cốt lõi có từ @since 1.0.0. Hệ phân cấp action có từ @since 2.1.0. Hàm khởi tạo FileAttachment và AFRelationship xuất hiện ở @since 1.8.0 / @since 1.1.0.

Bề mặt API

Lớp	Thành viên chính	Vai trò
`AnnotationManager`	`addAnnotation()`, `addFreeText()`, `addLine()`, `addSquare()`, `addCircle()`, `addPolygon()`, `addInk()`, `addHighlight()`, `addUnderline()`	Trình dựng chú thích với đầu vào được bảo vệ trước injection (`@since 1.0.0`)
`LinkManager`	`addLink()`, `setLink()`, `setDestination()`, `addLinkAnnotation()`, `addUrlAnnotation()`, `preallocateAnnotationObjects()`	Liên kết nội bộ, điểm đến có tên, chú thích URL (`@since 1.0.0`)
`BookmarkManager`	`addBookmark()`, `hasBookmarks()`, `write()`	Cây đại cương tài liệu (bookmark) (`@since 1.0.0`)
`TocBuilder`	`addEntry()`, `hasEntries()`, `render()`, `getEntries()`	Mục lục trên trang (`@since 1.0.0`)
`Action` (interface)	`subtype()`, `toDictionary()`, `withNext()`, `nextChain()`	Hành động trigger + chuỗi hành động (`@since 2.1.0`)
`PageTransition`	`toDict()`, `toInlineDict()`	Hiệu ứng chuyển trang trình chiếu (`@since 1.2.0`)
`FileAttachment`	`embedFile()`, `embedFileFromString()`, `hasAttachments()`, `getCount()`, `writeAttachments()`	Tệp đính kèm nhúng (`@since 1.0.0`)
`AFRelationship` (enum)	`toPdfName()`	Quan hệ tệp liên kết (`@since 1.1.0`)
`AnnotationFlags`	`with()`, `without()`, `has()`, `toInt()`	Tập cờ chú thích bất biến (`@since 1.2.0`)

Chạy composer docs:generate-api-php -- --module=Navigation để tạo bảng PHPDoc đầy đủ.

Mã ví dụ — bắt đầu nhanh

examples/12-bookmarks-and-toc.php xây dựng đại cương tài liệu thông qua facade cấp cao bao quanh BookmarkManager. Để dùng trực tiếp 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.
}

Mã ví dụ — môi trường sản xuất

Nhúng tệp đính kèm với quan hệ tệp liên kết rõ ràng, rồi kiểm tra kết quả trước khi hoàn tất tài liệu.

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

Trường hợp đặc biệt & lưu ý

AnnotationManager âm thầm chuẩn hóa đầu vào độc hại: một subtype không hợp lệ sẽ trở thành mặc định, một icon không phải name sẽ trở thành icon mặc định, và QuadPoints sai định dạng sẽ bị bỏ qua. Chú thích vẫn được tạo ra; hãy xác thực đầu vào từ trước nếu bạn cần giữ nguyên chính xác các giá trị đó.
LinkManager::preallocateAnnotationObjects() phải chạy trước khi Writer tuần tự hóa các tham chiếu; nếu không, đích của liên kết sẽ không trỏ tới đâu cả.
Action::withNext() trả về một hành động mới có chuỗi được gắn kèm; interface hỗ trợ nối chuỗi theo kiểu bất biến, không thay đổi tại chỗ.
FileAttachment::writeAttachments() cần một ObjectRegistry đang hoạt động từ Writer. Khi được gọi riêng lẻ, manager chỉ tích lũy ý định và không ghi gì cho đến khi Writer điều khiển nó.
AnnotationFlags là một tập cờ bất biến. with()/without() trả về một thể hiện mới; bản gốc không thay đổi.

Hiệu năng

Việc tích lũy chú thích, liên kết và bookmark là O(n) theo số lượng mục và không thực hiện reflow. Chi phí của tệp đính kèm nhúng chủ yếu do kích thước byte nhúng quyết định, không phải do chi phí của manager. Khối lượng công việc tham chiếu mặc định nằm trong ngân sách 1500 ms thời gian thực / 64 MB đỉnh. Hồ sơ khả năng tái lập là structural: số hiệu đối tượng và /ID trong trailer khác nhau giữa các lần chạy. Hai tài liệu có cùng ý định điều hướng sẽ tương đương về mặt cấu trúc, nhưng không giống nhau từng byte.

Lưu ý bảo mật

AnnotationManager xem subtype chú thích, icon và QuadPoints là dữ liệu không đáng tin cậy. Nó xác thực từng giá trị theo danh sách cho phép hoặc theo mẫu, rồi thay thế giá trị xấu thay vì ghi thẳng qua. Điều này chặn một hướng tấn công PDF name-injection. LinkManager::addUrlAnnotation() mã hóa một URL thành một hành động liên kết. URL vẫn là ranh giới tin cậy của bên sử dụng: một URL độc hại vẫn có thể hợp lệ, vì vậy hãy làm sạch các đích trước khi thêm chúng. FileAttachment nhúng byte tùy ý. Hãy giới hạn kích thước nhúng và xem mọi nguồn tệp đính kèm do người dùng cung cấp là không đáng tin cậy. Xem mô hình mối đe dọa của engine tại /modules/core/security/.

Tuân thủ

Các cấu trúc mà mô-đun này phát ra tuân theo ISO 32000-2 §12 cho chú thích, hành động, điểm đến và cây phân cấp đại cương tài liệu. Các tham chiếu điều khoản theo từng tính năng (icon chú thích §12.5.6.4, QuadPoints của text-markup §12.5.6.10, hành động §12.6) được ghi chú trực tiếp trong src/Navigation/ và được kiểm thử bởi tests/Unit/Navigation/. Đây là thực tế triển khai, không phải tuyên bố về tuân thủ PDF 2.0 đầu cuối. Tuân thủ toàn tài liệu được xác thực bởi oracle và các bộ golden được mô tả trong /modules/core/conformance/.

Xem thêm

Mô-đun Document
Mô-đun Multimedia — các đối tượng rendition do một hành động rendition phát ra.
Mô-đun Writer — tuần tự hóa các cấu trúc điều hướng.
Tổng quan tuân thủ
Mô hình bảo mật của engine