Navegação (HasNavigation)

O trait HasNavigation e seus módulos subjacentes (BookmarkManager, TocManager, AnnotationManager, FileAttachment) fornecem funcionalidades de navegação PDF: marcadores hierárquicos, sumário auto-gerado, links internos e externos, destinos nomeados, anotações e anexos de arquivo incorporados. Todos os métodos retornam static, então cada chamada pode ser encadeada.

Referência Rápida

Método	Funcionalidade
bookmark()	Adicionar marcador / entrada de outline hierárquico
addTOC()	Auto-gerar sumário com pontos condutores
addHTMLTOC()	Sumário estilizado com HTML
addLink()	Criar destino de link interno (retorna ID do link)
setLink()	Definir posição alvo do link interno
setDestination()	Criar âncora de destino nomeado
annotation()	Adicionar anotação de texto
addFileAttachment()	Incorporar anexo de arquivo no PDF

Exemplo Básico

use Yeeefang\TcpdfNext\Core\Document;

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

    // Marcadores
    ->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)

    // Link interno
    ->addPage()
    ->bookmark('Chapter 2', 0)
    ->cell(0, 10, 'Chapter 2: Advanced Topics', newLine: true)

    // Anexo de arquivo
    ->addFileAttachment('/path/to/data.xlsx', 'data.xlsx', 'Supporting data')

    // Auto-gerar sumário no final (insere na página 1)
    ->addTOC(1, ' . ', 'Table of Contents');

Marcadores / Outlines

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

Os marcadores aparecem no painel de outline do leitor PDF. Aninhe-os incrementando $level.

Sumário

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

Chame addTOC() depois que todos os marcadores foram adicionados. O sumário é construído a partir da árvore de marcadores e inserido na posição de página especificada. Use addHTMLTOC() para controle total sobre a estilização de entradas via HTML e CSS.

Links Internos

Crie referências cruzadas clicáveis entre páginas:

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

Links Externos

Passe uma string URL como parâmetro $link em cell(), write() ou image():

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

Destinos Nomeados

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

Destinos nomeados permitem que documentos externos ou URLs façam link para um local específico via fragmento #name.

Anotações

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

As anotações aparecem como ícones de notas adesivas no visualizador PDF.

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

Anexos de Arquivo

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

Arquivos incorporados aparecem no painel de anexos do leitor PDF.

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