导航（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 会自动追踪页码变化。