導航（HasNavigation）

HasNavigation trait 及其底層模組（BookmarkManager、TocManager、AnnotationManager、FileAttachment）提供 PDF 文件的導航功能：階層式書籤、自動產生的目錄、內部與外部連結、命名目的地、註解，以及嵌入式檔案附件。所有方法皆回傳 static，支援方法鏈（method chaining）。

快速參考

方法	功能
bookmark()	新增階層式書籤（大綱項目）
addTOC()	自動產生附帶導引點的目錄
addHTMLTOC()	使用 HTML 樣式的目錄
addLink()	建立內部連結目的地（回傳連結 ID）
setLink()	設定內部連結的目標位置
setDestination()	建立命名目的地錨點
annotation()	新增文字註解
addFileAttachment()	在 PDF 中嵌入檔案附件

基本範例

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12)

    // 書籤
    ->bookmark('Chapter 1', 0)
    ->cell(0, 10, 'Chapter 1: Introduction', newLine: true)
    ->bookmark('Section 1.1', 1)
    ->cell(0, 10, '1.1 Getting Started', newLine: true)

    // 內部連結
    ->addPage()
    ->bookmark('Chapter 2', 0)
    ->cell(0, 10, 'Chapter 2: Advanced Topics', newLine: true)

    // 檔案附件
    ->addFileAttachment('/path/to/data.xlsx', 'data.xlsx', 'Supporting data')

    // 在最後自動產生目錄（插入至第 1 頁）
    ->addTOC(1, ' . ', 'Table of Contents');

書籤（Bookmarks）

$pdf->bookmark(
    string $txt,
    int    $level = 0,
    float  $y     = -1,
    int    $page  = -1,
    string $style = '',
    array  $color = []
);

書籤會顯示在 PDF 閱讀器的大綱面板中。透過遞增 $level 來建立巢狀的階層結構：

$pdf->bookmark('第一章：概述', 0)                 // 第一層
    ->cell(0, 10, '第一章：概述', newLine: true)
    ->bookmark('1.1 背景說明', 1)                  // 第二層
    ->cell(0, 10, '1.1 背景說明', newLine: true)
    ->bookmark('1.1.1 歷史沿革', 2)                // 第三層
    ->cell(0, 10, '1.1.1 歷史沿革', newLine: true);

參數	說明
$txt	書籤顯示的文字
$level	階層深度（0 為最頂層）
$y	Y 座標（-1 = 目前位置）
$page	目標頁碼（-1 = 目前頁面）
$style	文字樣式：B（粗體）、I（斜體）、BI（粗斜體）
$color	RGB 色彩陣列，例如 [255, 0, 0]

目錄（TOC）

addTOC()

$pdf->addTOC(int $page, string $numberSuffix = '', string $bookmarkText = '');

在所有書籤建立完成後呼叫 addTOC()。目錄會根據書籤樹自動產生，並插入到指定的頁碼位置。頁碼以導引點連接，呈現專業的排版效果。

$pdf->addTOC(1, ' . ', '目錄');

addHTMLTOC()

如果需要完整控制目錄的排版樣式，可以改用 addHTMLTOC()，透過 HTML 和 CSS 自訂每個目錄項目的外觀：

$pdf->addHTMLTOC(1, '目錄', [
    'font-size' => '14pt',
    'font-weight' => 'bold',
]);

內部連結（Links）

建立頁面之間可點擊的交叉參考：

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', '', 12);

// 步驟一：建立連結 ID
$linkId = $pdf->addLink();

// 步驟二：在文字中使用連結
$pdf->write(10, 'Jump to Chapter 2', link: $linkId)

    // 步驟三：在目標頁面設定連結位置
    ->addPage()
    ->setLink($linkId, y: 0)
    ->cell(0, 10, 'Chapter 2 starts here', newLine: true);

流程很簡單：先用 addLink() 取得連結 ID，接著在來源位置引用這個 ID，最後在目標位置呼叫 setLink() 設定實際跳轉目標。

外部連結

在 cell()、write() 或 image() 的 $link 參數中直接傳入 URL 字串：

$pdf->cell(0, 10, 'Visit our website', link: 'https://example.com', newLine: true)
    ->write(10, 'Click here', link: 'https://docs.example.com');

命名目的地（Named Destinations）

$pdf->setDestination(string $name, float $y = -1, int $page = -1);

命名目的地讓外部文件或 URL 可以透過 #name 片段連結（fragment）跳轉到 PDF 中的特定位置。這在跨文件引用時特別實用：

$pdf->setDestination('appendix-a')
    ->cell(0, 10, 'Appendix A: Data Tables', newLine: true);

外部連結便可使用 document.pdf#appendix-a 直接跳轉到此處。

註解（Annotations）

$pdf->annotation(
    float  $x,
    float  $y,
    float  $w,
    float  $h,
    string $text,
    array  $opt = []
);

註解在 PDF 閱讀器中會顯示為便利貼圖示，供審閱或標記用途：

$pdf->annotation(50, 80, 10, 10, 'Review this section before release.', [
    'subtype' => 'Text',
    'icon'    => 'Comment',
    'color'   => [255, 255, 0],
]);

選項	說明
subtype	註解子類型，例如 Text
icon	圖示名稱：Comment、Note、Help、Insert 等
color	RGB 色彩陣列

檔案附件（Attachments）

$pdf->addFileAttachment(string $file, string $name, string $desc);

嵌入的檔案會顯示在 PDF 閱讀器的附件面板中，適合附帶原始資料或補充文件：

$pdf->addFileAttachment('/reports/q4-data.xlsx', 'q4-data.xlsx', 'Q4 財務資料')
    ->addFileAttachment('/reports/methodology.pdf', 'methodology.pdf', '研究方法說明');

完整範例：技術手冊導航

use Yeeefang\TcpdfNext\Core\Document;

$pdf = Document::create()
    ->addPage()
    ->setFont('Helvetica', 'B', 18)
    ->cell(0, 15, 'Technical Manual', newLine: true)
    ->setFont('Helvetica', '', 12)

    // 第一章
    ->bookmark('1. Installation', 0)
    ->cell(0, 10, '1. Installation', newLine: true)
    ->bookmark('1.1 Requirements', 1)
    ->cell(0, 10, '1.1 System Requirements', newLine: true)
    ->cell(0, 8, 'PHP 8.5+ is required...', newLine: true)

    // 第二章
    ->addPage()
    ->bookmark('2. Configuration', 0)
    ->cell(0, 10, '2. Configuration', newLine: true)
    ->annotation(150, 10, 10, 10, 'This chapter needs updating for v2.', [
        'subtype' => 'Text',
        'icon'    => 'Note',
        'color'   => [255, 200, 0],
    ])

    // 附件
    ->addFileAttachment('/docs/config-sample.yaml', 'config-sample.yaml', 'Sample configuration')

    // 在最前面插入目錄
    ->addTOC(1, ' . ', 'Table of Contents');

提示

• 書籤文字支援 Unicode，可以直接使用中文或其他多語言文字。
• addTOC() 必須在所有書籤都已建立之後才呼叫，否則目錄會不完整。
• 檔案附件會增加 PDF 的檔案大小，請留意嵌入大型附件的影響。
• 內部連結在文件重新分頁後仍然有效，TCPDF-Next 會自動追蹤頁碼變化。