Навигация (HasNavigation)

Trait HasNavigation и его подмодули (BookmarkManager, TocManager, AnnotationManager, FileAttachment) обеспечивают навигацию по PDF: иерархические закладки, автоматически генерируемое оглавление, внутренние и внешние ссылки, именованные назначения, аннотации и встроенные вложения файлов. Все методы возвращают static, поэтому каждый вызов может быть объединён в цепочку.

Краткий справочник

Метод	Функция
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');

Закладки / Контуры

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

Закладки отображаются в панели оглавления PDF-просмотрщика. Вложенность создаётся увеличением $level.

Оглавление

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

Вызывайте addTOC() после добавления всех закладок. Оглавление строится из дерева закладок и вставляется на указанную позицию страницы. Используйте addHTMLTOC() для полного контроля стилизации записей через HTML и CSS.

Внутренние ссылки

Создание кликабельных перекрёстных ссылок между страницами:

use Yeeefang\TcpdfNext\Core\Document;

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

$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);

Внешние ссылки

Передайте URL-строку как параметр $link в cell(), write() или image():

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

Именованные назначения

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

Именованные назначения позволяют внешним документам или URL ссылаться на конкретное местоположение через фрагмент #name.

Аннотации

$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],
]);

Вложенные файлы

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

Встроенные файлы отображаются в панели вложений PDF-просмотрщика.

$pdf->addFileAttachment('/reports/q4-data.xlsx', 'q4-data.xlsx', 'Q4 financial data')
    ->addFileAttachment('/reports/methodology.pdf', 'methodology.pdf', 'Research methodology');