Sumário

Visão geral

NextPDF\Pro\Toc coleta cabeçalhos H1–H6 do HTML e renderiza um sumário paginado de vários níveis como operadores de fluxo de conteúdo PDF. Os números de página são fornecidos pelo chamador (ou placeholders sequenciais); o módulo não resolve referências cruzadas dinâmicas do documento.

Disponibilidade e licenciamento

Este recurso está incluído no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem esse direito de uso não carrega as classes do recurso. As classes do Toc são carregadas sempre que nextpdf/pro está instalado; nenhum sinalizador de capacidade em tempo de execução restringe o módulo. Compare edições e obtenha uma licença.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

O fluxo de trabalho tem duas fases:

• Coleta. AutoTocCollector::extract($html, maxDepth) varre o HTML em busca de tags <h1>–<h6> até o limite de profundidade, remove a marcação interna, decodifica as entidades, normaliza o espaço em branco e emite objetos de valor TocHeading (nível 0 = H1). Ele pode atribuir números de página sequenciais ou aplicar um mapa de índice para página fornecido pelo chamador.
• Renderização. AutoTocRenderer::render($headings, $config) produz uma string de fluxo de conteúdo PDF por página do sumário, com recuo por nível, pontilhados (dot leaders) opcionais e números de página opcionais. Cada linha visível é emitida como uma operação de exibição de texto Tj conforme ISO 32000-2:2020 §9.4.

AutoTocConfig é um objeto de valor imutável, configurado de forma fluente, que controla título, profundidade, fontes, espaçamento, margens, cores, tamanho da página e se os pontilhados e os números de página são exibidos.

Por que funciona assim

A decisão fundamental é que o módulo nunca inventa um número de página que não pode conhecer. As páginas de destino reais dependem do documento final com layout aplicado, que pertence ao chamador; uma suposição desviaria silenciosamente sempre que a paginação mudasse. Por isso, a coleta e a renderização permanecem desacopladas do layout. AutoTocCollector emite cabeçalhos com páginas null ou placeholder; os números de página reais chegam apenas por meio de um mapa assignPageNumbers() fornecido pelo chamador. A renderização então produz operadores de fluxo de conteúdo simples, deixando a colocação das páginas a cargo do chamador. O resultado permanece determinístico e honesto: o módulo declara o que não sabe em vez de fabricá-lo.

Antecedentes de design: Uma API que se recusa a adivinhar.

Contrato de comportamento

• Entrada. HTML (coleta) e uma lista de TocHeading (renderização).
• Saída. list<TocHeading> da coleta; list<string> de operadores de fluxo de conteúdo PDF (um por página do sumário) da renderização.
• Números de página. Atribuídos sequencialmente, fornecidos via um mapa de índice para página, ou deixados como null. O módulo não calcula as páginas de destino reais a partir de um documento com layout aplicado; ele não resolve referências cruzadas.
• Profundidade. maxDepth é limitado a 1–6. Os cabeçalhos mais profundos que a profundidade configurada são pulados.
• Determinismo. Para HTML e configuração idênticos, os cabeçalhos coletados e os operadores renderizados são estáveis.

Superfície da API pública

Tipo	Categoria	Membros principais
NextPDF\Pro\Toc\AutoTocCollector	final class	static extract(string $html, int $maxDepth = 6): list<TocHeading>, scan(string $html): void, assignSequentialPages(int $startPage = 1): list<TocHeading>, assignPageNumbers(array $pageMap): list<TocHeading>
NextPDF\Pro\Toc\AutoTocRenderer	final class	static render(array $headings, ?AutoTocConfig $config = null): list<string>
NextPDF\Pro\Toc\AutoTocConfig	final readonly class	default(), landscape(), letter(), withTitle(), withMaxDepth(), withFontSize(), withDotLeader(), withPageNumbers(), withIndentPerLevel(), entriesPerPage(): int
NextPDF\Pro\Toc\TocHeading	final readonly class	string $title, int $level, ?int $pageNumber, float $y, withPageNumber(), withPosition(), hasPageNumber(): bool

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

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocRenderer;

$headings = AutoTocCollector::extract($html, maxDepth: 3);
$streams  = AutoTocRenderer::render($headings);

echo count($streams), " TOC page(s) of content-stream operators\n";

Exemplo de código — Produção

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocConfig;
use NextPDF\Pro\Toc\AutoTocRenderer;

function buildToc(string $html, array $headingPageMap): array
{
    $collector = new AutoTocCollector(maxDepth: 4);
    $collector->scan($html);

    // Caller supplies real page numbers from its own layout pass.
    $headings = $collector->assignPageNumbers($headingPageMap);

    $config = AutoTocConfig::default()
        ->withTitle('Contents')
        ->withMaxDepth(4)
        ->withDotLeader(true)
        ->withPageNumbers(true);

    return AutoTocRenderer::render($headings, $config);
}

Casos extremos e armadilhas

• Texto de cabeçalho vazio (após a remoção de tags) é pulado.
• maxDepth é limitado a 1–6 tanto no collector quanto na config; valores fora do intervalo são corrigidos, não rejeitados.
• Os números de página são placeholders, a menos que o chamador forneça um mapa real; o módulo não executa uma passagem de layout para descobrir as páginas de destino reais.
• O renderizador emite operadores de fluxo de conteúdo para colocação em uma página; o chamador é responsável por adicionar essas páginas ao documento.

Desempenho

A coleta é uma única passagem de expressão regular sobre o HTML. A renderização é linear em relação à contagem de cabeçalhos, paginada por entriesPerPage(). Consulte performance_budget.

Notas de segurança

O HTML é varrido com uma expressão regular de cabeçalho delimitada e remoção de tags; nenhum HTML é executado e nenhuma referência externa é seguida. O texto renderizado é escapado para a sintaxe de string de fluxo de conteúdo.

Conformidade

Afirmação	Cláusula da especificação	Status
Linhas do sumário emitidas como operações de exibição de texto Tj	ISO 32000-2:2020 §9.4	Verificado (conjunto de testes unitários)
Resolução de referência cruzada dinâmica do documento	—	Não suportado (números de página fornecidos pelo chamador)

Fallback / alternativa do Core

Não há gerador de sumário no Core. O HTML de origem dos cabeçalhos normalmente vem do pipeline HTML do Core. Consulte /modules/core/html/.

Nota sobre o limite do Enterprise

Este módulo coleta cabeçalhos e renderiza operadores de sumário. Ele não realiza resolução de referências cruzadas em todo o documento, geração de índice remissivo ou sincronização da árvore de marcadores; essas preocupações estão fora do escopo.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública da API suportada. Caminhos de namespace internos, classes auxiliares, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de ticket estão fora do escopo.

Veja também

• Referência do sumário (TOC)
• Merge
• Template
• Pipeline HTML do Core