Navegação: anotações, links, outlines, ações e anexos

Visão geral

O módulo Navigation constrói a camada interativa do Portable Document Format (PDF). Ele abrange anotações, anotações de link e de Uniform Resource Locator (URL), o outline do documento (bookmarks), o sumário, ações e cadeias de gatilhos, transições de página e anexos de arquivos incorporados com suas relações de arquivo associado.

Instalação

composer require nextpdf/core:^3

Visão conceitual

A ISO 32000-2 §12 define os recursos interativos de um documento PDF: anotações, ações, destinos e o outline do documento. Este módulo implementa essa camada no engine. As classes manager coletam a intenção; os value objects transportam os dados emitidos por esses managers.

AnnotationManager é o ponto de entrada mais abrangente. Ele adiciona anotações de texto, texto livre, linha, quadrado, círculo, polígono, polilinha, tinta e marcação de texto (destaque e sublinhado). Ele foi reforçado contra entradas hostis: um subtipo de anotação desconhecido cai em um padrão seguro, um nome de ícone que não é um name token PDF válido é substituído, e os QuadPoints de marcação de texto devem ser fornecidos como um múltiplo de oito floats ou são descartados. Essas verificações são defesas contra injeção em PDF, não conveniências de validação. LinkManager lida com links internos, destinos nomeados e anotações de URL. Ele pré-aloca objetos de anotação para que o Writer possa referenciá-los antes da serialização.

BookmarkManager e TocBuilder constroem a hierarquia de navegação. O outline do documento é a árvore de bookmarks exibida pelo visualizador na barra lateral. TocBuilder renderiza um sumário na página e pode usar FontMetrics para o layout de leader/width. OutlineAutoGenerator deriva um outline a partir da estrutura do documento.

A hierarquia Action em NextPDF\Navigation\Action modela o comportamento orientado por gatilho: GoTo (remoto e incorporado), launch, named, hide, reset/submit de formulário e definição de estado de conteúdo opcional. A ação de rendition de anotação de tela da §13 está adiada; é trabalho futuro e ainda não está conectada. Não confie nela como uma ação com suporte. Action::withNext() constrói a cadeia de ações executada para um único evento de gatilho. PageTransition modela uma transição de apresentação. FileAttachment incorpora um arquivo a partir de um caminho ou de uma byte string e o marca com um AFRelationship (o enum de relação de arquivo associado). Ele retorna um FileAttachmentResult e escreve por meio de writeAttachments(). Os managers core são @since 1.0.0. A hierarquia de ações é @since 2.1.0. O construtor de FileAttachment e AFRelationship chegaram em @since 1.8.0 / @since 1.1.0.

Superfície da API

Classe	Membros principais	Função
AnnotationManager	addAnnotation(), addFreeText(), addLine(), addSquare(), addCircle(), addPolygon(), addInk(), addHighlight(), addUnderline()	Construtor de anotações com entradas seguras contra injeção (@since 1.0.0)
LinkManager	addLink(), setLink(), setDestination(), addLinkAnnotation(), addUrlAnnotation(), preallocateAnnotationObjects()	Links internos, destinos nomeados, anotações de URL (@since 1.0.0)
BookmarkManager	addBookmark(), hasBookmarks(), write()	Árvore do outline (bookmark) do documento (@since 1.0.0)
TocBuilder	addEntry(), hasEntries(), render(), getEntries()	Sumário na página (@since 1.0.0)
Action (interface)	subtype(), toDictionary(), withNext(), nextChain()	Ação de gatilho + cadeia de ações (@since 2.1.0)
PageTransition	toDict(), toInlineDict()	Transição de página de apresentação (@since 1.2.0)
FileAttachment	embedFile(), embedFileFromString(), hasAttachments(), getCount(), writeAttachments()	Anexos de arquivo incorporado (@since 1.0.0)
AFRelationship (enum)	toPdfName()	Relação de arquivo associado (@since 1.1.0)
AnnotationFlags	with(), without(), has(), toInt()	Conjunto imutável de flags de anotação (@since 1.2.0)

Execute composer docs:generate-api-php -- --module=Navigation para gerar a tabela completa de PHPDoc.

Exemplo de código — Início rápido

examples/12-bookmarks-and-toc.php constrói o outline do documento por meio do facade de alto nível que encapsula BookmarkManager. Para usar o manager diretamente:

<?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.
}

Exemplo de código — Produção

Incorpore um anexo com uma relação de arquivo associado explícita e, em seguida, verifique o resultado antes de finalizar o documento.

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

Casos extremos e armadilhas

• AnnotationManager normaliza silenciosamente entradas hostis: um subtipo inválido torna-se o padrão, um ícone que não é um nome torna-se o ícone padrão, e QuadPoints malformados são descartados. A anotação ainda é produzida; valide as entradas a montante se precisar que elas sejam respeitadas exatamente.
• LinkManager::preallocateAnnotationObjects() deve ser executado antes de o Writer serializar as referências; caso contrário, os alvos dos links não serão resolvidos.
• Action::withNext() retorna uma nova ação com a cadeia anexada; a interface oferece suporte a encadeamento imutável, não a mutação no local.
• FileAttachment::writeAttachments() requer um ObjectRegistry ativo do Writer. Quando chamado isoladamente, o manager acumula a intenção, mas não escreve nada até que o Writer o conduza.
• AnnotationFlags é um conjunto imutável de flags. with()/without() retornam uma nova instância; o original permanece inalterado.

Desempenho

A acumulação de anotações, links e bookmarks é O(n) em relação ao número de itens e não executa reflow. O custo de um anexo de arquivo incorporado é dominado pelo tamanho em bytes do conteúdo incorporado, não pelo overhead do manager. A carga de trabalho de referência padrão permanece dentro do orçamento de 1500 ms de wall / 64 MB de pico. O perfil de reprodutibilidade é structural: os números dos objetos e o /ID do trailer diferem entre execuções. Dois documentos com a mesma intenção de navegação são estruturalmente equivalentes, mas não idênticos byte a byte.

Notas de segurança

AnnotationManager trata o subtipo de anotação, o ícone e os QuadPoints como não confiáveis. Ele valida cada valor contra uma allow-list ou um padrão e substitui valores inválidos em vez de escrevê-los adiante. Isso fecha um vetor de injeção de nomes em PDF. LinkManager::addUrlAnnotation() codifica uma URL em uma ação de link. A URL continua sendo a fronteira de confiança do consumidor: uma URL hostil ainda pode ser válida, portanto sanitize os destinos antes de adicioná-los. FileAttachment incorpora bytes arbitrários. Limite o tamanho incorporado e trate qualquer origem de anexo fornecida pelo usuário como não confiável. Consulte o modelo de ameaças do engine em /modules/core/security/.

Conformidade

As estruturas emitidas por este módulo seguem a ISO 32000-2 §12 para anotações, ações, destinos e a hierarquia de outline do documento. As referências de cláusula por recurso (ícones de anotação §12.5.6.4, QuadPoints de marcação de texto §12.5.6.10, ações §12.6) estão documentadas inline em src/Navigation/ e exercitadas por tests/Unit/Navigation/. Esses são fatos de implementação, não uma declaração de conformidade PDF 2.0 de ponta a ponta. A conformidade do documento completo é validada pelas suítes oracle e golden descritas em /modules/core/conformance/.

Veja também

• Módulo Document
• Módulo Multimedia — os objetos rendition que uma ação de rendition reproduz.
• Módulo Writer — serializa as estruturas de navegação.
• Visão geral de conformidade
• Modelo de segurança do engine