跳到內容
NextPDF

導覽：註解、連結、大綱、動作與附件

概觀

標題為「概觀」的區段

導覽模組負責建構 PDF 的互動層：註解、連結與 URL 註解、文件大綱（書籤）與目錄、動作與觸發鏈、頁面轉場，以及附帶關聯檔案關係的內嵌檔案附件。

安裝

標題為「安裝」的區段
Terminal window
composer require nextpdf/core:^3

概念總覽

標題為「概念總覽」的區段

ISO 32000-2 §12 定義 PDF 的互動功能——註解、動作、目的地與文件大綱。本模組是引擎針對這一層使用的編碼器。整體由一組累積意圖的管理員類別，以及這些管理員產出的值物件組成。

AnnotationManager 是涵蓋範圍最廣的介面。它可加入文字、自由文字、線段、矩形、圓形、多邊形、折線、墨跡，以及文字標記類註解（醒目提示、底線）。它經過強化：未知的註解子類型會回退為安全的預設值，不是有效 PDF 名稱符記的圖示名稱會被替換，而文字標記的 QuadPoints 必須以八的倍數個浮點數傳入，否則會被捨棄。這些是 PDF 注入防禦措施，並非驗證上的便利功能。LinkManager 負責處理內部連結、具名目的地與 URL 註解。它會預先配置註解物件，讓 Writer 在序列化之前就能參照它們。

BookmarkManager 與 TocBuilder 負責建構導覽階層。文件大綱就是檢視器在側欄顯示的書籤樹；TocBuilder 則在頁面上繪製目錄，並可使用 FontMetrics 進行 leader/width 版面配置。OutlineAutoGenerator 會從文件結構推導出大綱。

Action 階層位於 NextPDF\Navigation\Action 之下，用以建模由觸發器驅動的行為：GoTo（遠端與內嵌）、launch、named、hide、表單的 reset/submit，以及設定選用內容狀態。§13 的螢幕註解播放動作目前延後處理：它屬於未來工作且尚未接通，因此請勿將它當作受支援的動作來依賴。Action::withNext() 會建構在單一觸發事件下執行的動作鏈。PageTransition 用以建模簡報轉場。FileAttachment 會從路徑或位元組字串內嵌檔案，並以 AFRelationship（關聯檔案關係列舉）加上標記。它會回傳一個 FileAttachmentResult，並透過 writeAttachments() 寫出。核心管理員標示為 @since 1.0.0。動作階層標示為 @since 2.1.0。FileAttachment 建構式與 AFRelationship 分別在 @since 1.8.0 / @since 1.1.0 推出。

API 介面

標題為「API 介面」的區段
類別主要成員角色
AnnotationManageraddAnnotation()、addFreeText()、addLine()、addSquare()、addCircle()、addPolygon()、addInk()、addHighlight()、addUnderline()對輸入具備注入防護的註解建構器（@since 1.0.0）
LinkManageraddLink()、setLink()、setDestination()、addLinkAnnotation()、addUrlAnnotation()、preallocateAnnotationObjects()內部連結、具名目的地、URL 註解（@since 1.0.0）
BookmarkManageraddBookmark()、hasBookmarks()、write()文件大綱（書籤）樹（@since 1.0.0）
TocBuilderaddEntry()、hasEntries()、render()、getEntries()頁面上的目錄（@since 1.0.0）
Action（介面）subtype()、toDictionary()、withNext()、nextChain()觸發式動作與動作鏈（@since 2.1.0）
PageTransitiontoDict()、toInlineDict()簡報頁面轉場（@since 1.2.0）
FileAttachmentembedFile()、embedFileFromString()、hasAttachments()、getCount()、writeAttachments()內嵌檔案附件（@since 1.0.0）
AFRelationship（列舉）toPdfName()關聯檔案關係（@since 1.1.0）
AnnotationFlagswith()、without()、has()、toInt()不可變的註解旗標集合（@since 1.2.0）

可執行 composer docs:generate-api-php -- --module=Navigation 取得完整的 PHPDoc 表格。

程式碼範例——快速上手

標題為「程式碼範例——快速上手」的區段

原始碼中的 examples/12-bookmarks-and-toc.php 會透過包裝 BookmarkManager 的高階外觀建構文件大綱。若要直接使用管理員：

<?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 序列化參照之前執行，否則連結目標會解析為空。
  • Action::withNext() 會回傳一個附上動作鏈的新動作；此介面是為不可變的動作鏈而設計，並非原地變更。
  • FileAttachment::writeAttachments() 需要 Writer 提供一個運作中的 ObjectRegistry。單獨呼叫管理員只會累積意圖，但在 Writer 驅動它之前不會寫出任何內容。
  • AnnotationFlags 是不可變的旗標集合。with()/without() 會回傳新的實例；原本的實例不會變動。

效能

標題為「效能」的區段

註解、連結與書籤的累積在項目數量上是 O(n)，且不會重排版面。內嵌檔案附件的成本主要由內嵌的位元組大小決定，而非由管理員決定。預設的參考工作負載落在 1500 毫秒牆鐘時間/64 MB 尖峰的預算之內。可重現性設定檔是 structural：物件編號與尾段的 /ID 會在不同次執行之間有所差異。兩份具有相同導覽意圖的文件在結構上相等，但並非位元組完全相同。

安全注意事項

標題為「安全注意事項」的區段

AnnotationManager 將註解子類型、圖示與 QuadPoints 視為不可信：每一項都會比對允許清單或樣式來驗證，不合法值會被替換而非直接寫出。這封鎖了一條 PDF 名稱注入途徑。LinkManager::addUrlAnnotation() 會把 URL 編碼成連結動作。URL 的信任責任在使用者端——惡意的 URL 仍是有效的 URL，因此加入目的地前請先進行清理。FileAttachment 會內嵌任意位元組。請限制內嵌大小，並在附件來源來自使用者時將其視為不可信。請參閱 /modules/core/security/ 中的引擎威脅模型。

符合性

標題為「符合性」的區段

本模組產生的結構遵循 ISO 32000-2 §12——註解、動作、目的地——以及文件大綱階層。各項功能的條款參照（註解圖示 §12.5.6.4、文字標記 QuadPoints §12.5.6.10、動作 §12.6）在 src/Navigation/ 中以行內方式記載，並由 tests/Unit/Navigation/ 進行驗證。這些是實作事實，並非端對端 PDF 2.0 符合性的聲明。整份文件的符合性由 /modules/core/conformance/ 中所述的 oracle 與黃金測試套件來驗證。

另請參閱

標題為「另請參閱」的區段