Sumário — Referência Profunda

Visão geral

Esta página é a referência em nível de contrato para o módulo Toc do NextPDF Pro, NextPDF\Pro\Toc. AutoTocCollector varre o HTML em busca de cabeçalhos H1–H6 e emite objetos de valor TocHeading. AutoTocRenderer pagina esses cabeçalhos e renderiza cada página do TOC como operadores de fluxo de conteúdo PDF. AutoTocConfig é a configuração de renderização imutável. Os números de página são fornecidos pelo chamador ou são marcadores sequenciais; o módulo não resolve referências cruzadas dinâmicas do documento. Esta página descreve a API pública, o contrato de comportamento observável e os modos de falha. A configuração orientada a tarefas e os exemplos ficam na página de capacidade Sumário.

Disponibilidade e licenciamento

Esta capacidade é distribuída no NextPDF Pro (nextpdf/pro) e é ativada com um envelope de licença de nível Pro. Uma implantação sem essa habilitação não carrega as classes da capacidade. Compare as edições e obtenha uma licença.

Nenhum sinalizador de capacidade em tempo de execução restringe este módulo. As classes Toc podem ser usadas sempre que nextpdf/pro estiver instalado e licenciado.

Superfície da API pública

Símbolo	Parâmetros	Comportamento padrão	Retorna	Lança ou falha com	Notas
AutoTocCollector::__construct()	int $maxDepth = 6	Limita a profundidade ao intervalo 1–6	—	—	A instância acumula os cabeçalhos coletados
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Constrói, varre e retorna os cabeçalhos em uma única chamada	list<TocHeading>	—	Caminho rápido estático
AutoTocCollector::scan()	string $html	Corresponde H1–H6, remove a marcação, decodifica entidades, colapsa o espaço em branco e anexa os cabeçalhos não vazios	—	—	Altera o estado interno
AutoTocCollector::assignSequentialPages()	int $startPage = 1	Avança a página em cada cabeçalho de nível 0 após o primeiro	list<TocHeading>	—	Apenas numeração de marcador
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Aplica um mapa de índice para página; índices não mapeados mantêm sua página atual	list<TocHeading>	—	Páginas reais fornecidas pelo chamador
AutoTocCollector::getHeadings()	—	Retorna os cabeçalhos coletados	list<TocHeading>	—	—
AutoTocCollector::count()	—	Número de cabeçalhos coletados	int	—	—
AutoTocCollector::reset()	—	Limpa os cabeçalhos coletados	—	—	Reutilize o coletor entre varreduras
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Filtra por profundidade, pagina, emite um fluxo de conteúdo por página	list<string>	—	Retorna [] quando todos os cabeçalhos são filtrados
AutoTocConfig::__construct()	14 parâmetros tipados (título, profundidade, fontes, espaçamento, margens, cores, tamanho da página)	Portador de configuração imutável	—	—	Readonly; cores ChartColor têm preto como padrão
AutoTocConfig::default(), ::landscape(), ::letter()	—	Predefinições A4 retrato, A4 paisagem e US Letter	self	—	Fábricas estáticas
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	um valor cada	Retorna uma nova instância com o campo alterado; withMaxDepth() limita a 1–6	self	—	Fluente, não mutável
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Derivado
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Derivado
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	Sempre ≥ 1
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	Objeto de valor de cabeçalho imutável	—	—	Readonly; nível 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	número de página e/ou coordenada Y	Retorna uma nova instância com os campos de posição alterados	self	—	Fluente, não mutável
TocHeading::hasPageNumber()	—	True quando um número de página está atribuído	bool	—	—

public function __construct(int $maxDepth = 6)

public static function extract(string $html, int $maxDepth = 6): array

public function scan(string $html): void

public function assignSequentialPages(int $startPage = 1): array

public function assignPageNumbers(array $pageMap): array

public static function render(
    array $headings,
    ?AutoTocConfig $config = null,
): array

public function __construct(
    public string $title = 'Table of Contents',
    public int $maxDepth = 6,
    public float $fontSize = 10.0,
    public float $titleFontSize = 16.0,
    public float $indentPerLevel = 15.0,
    public float $lineHeight = 1.6,
    public bool $showPageNumbers = true,
    public bool $showDotLeader = true,
    public ChartColor $textColor = new ChartColor(0.0, 0.0, 0.0),
    public ChartColor $titleColor = new ChartColor(0.0, 0.0, 0.0),
    public float $leftMargin = 40.0,
    public float $topMargin = 50.0,
    public float $pageWidth = 595.28,
    public float $pageHeight = 841.89,
)

public function entriesPerPage(): int

public function __construct(
    public string $title,
    public int $level,
    public ?int $pageNumber = null,
    public float $y = 0.0,
)

public function withPageNumber(int $pageNumber): self

public function hasPageNumber(): bool

Contrato de comportamento

Coleta

AutoTocCollector::scan() corresponde <h1>–<h6> com um padrão delimitado (sem distinção de maiúsculas e minúsculas, com o ponto correspondendo à quebra de linha) que exige tags de abertura e fechamento balanceadas do mesmo nível. O conteúdo interno de cada correspondência tem as tags removidas, as entidades decodificadas (ENT_QUOTES | ENT_HTML5, UTF-8) e o espaço em branco colapsado. Resultados vazios são descartados. level é o número da tag menos um, portanto H1 é o nível 0. Uma tag mais profunda que maxDepth é ignorada. extract() é a fábrica de chamada única que combina construção, varredura e leitura.

Atribuição de número de página

Existem duas estratégias explícitas, ambas conduzidas pelo chamador.

• assignSequentialPages($startPage) avança o contador de página quando um cabeçalho de nível 0 é alcançado após a primeira entrada, então carimba cada cabeçalho.
• assignPageNumbers($pageMap) aplica um mapa de índice para página; um índice não mapeado mantém seu número de página existente.

Nenhuma das estratégias inspeciona um documento diagramado.

Renderização e paginação

AutoTocRenderer::render() mantém os cabeçalhos cujo level é inferior a maxDepth, retorna [] quando nada sobrevive, então divide o restante em blocos de AutoTocConfig::entriesPerPage(). Cada bloco se torna uma string de fluxo de conteúdo. Por entrada, o recuo é leftMargin + level * indentPerLevel; o tamanho da fonte diminui 0.5 pt por nível e tem um piso de 6.0 pt; o nível 0 usa a chave de fonte em negrito, os níveis mais profundos usam a chave regular. Quando os números de página estão habilitados e presentes, um preenchimento de pontos opcional preenche o espaço e o número é alinhado à direita. O título e cada string de entrada são exibidos com o operador Tj conforme ISO 32000-2:2020 §9.4, e cada string é escapada para a sintaxe de string literal PDF conforme §7.3.4.2. HTML e configuração idênticos produzem cabeçalhos e operadores estáveis.

Casos extremos e modos de falha

• Marcação de cabeçalho malformada não é coletada. Um <h2> não fechado sem um </h2> correspondente falha no padrão de par balanceado e é ignorado.
• Texto de cabeçalho vazio após a remoção de tags e o corte de espaços é descartado.
• maxDepth é limitado a 1–6 tanto no construtor do coletor quanto em AutoTocConfig::withMaxDepth(); valores fora do intervalo são corrigidos, não rejeitados.
• Os números de página são controlados pelo chamador. Nenhuma passagem de layout interna descobre a página real em que um cabeçalho cai, portanto o módulo não pode resolver referências cruzadas dinâmicas.
• O módulo não lança exceções. render() retorna um array vazio quando todos os cabeçalhos são filtrados por profundidade; nunca lança em entrada vazia.
• O dimensionamento colapsa para o piso max(1, …), portanto entriesPerPage() é sempre pelo menos 1 e a paginação sempre progride.
• O renderizador produz apenas operadores desenháveis. O chamador coloca os fluxos retornados em páginas reais e fornece os recursos /TocFont, /TocBoldFont e /TocTitleFont.

Comportamento em modo FIPS

Nenhuma operação criptográfica ocorre neste módulo, portanto não existe nenhum comportamento específico de modo FIPS. Nada aqui consome aleatoriedade, hashing ou assinatura.

Conformidade

Afirmação	Padrão	Cláusula
Título do TOC e texto de entrada exibidos com o operador de exibição de texto Tj	ISO 32000-2:2020	§9.4
Strings emitidas escapadas como strings literais PDF, com barra invertida duplicada e parênteses escapados	ISO 32000-2:2020	§7.3.4.2
Árvore PDF /Outlines ou links de destino nomeado	—	Não construído (apenas operadores de fluxo de conteúdo)
Resolução de referência cruzada dinâmica do documento	—	Sem suporte (números de página fornecidos pelo chamador)

Todas as cláusulas são parafraseadas; o NextPDF não reproduz texto normativo. Estas são declarações de capacidade, não certificações; o NextPDF não possui nenhuma certificação e não concede nenhuma.

Notas de desenvolvimento

• Disponibilidade dentro do pacote Pro: AutoTocCollector, AutoTocRenderer, AutoTocConfig e TocHeading desde a 1.9.0. Todos são atuais no nextpdf/pro 3.1.0.
• As cores de AutoTocConfig são valores NextPDF\Pro\Chart\ChartColor. As cores padrão de texto e título são pretas (0.0, 0.0, 0.0).
• Comece com AutoTocConfig::default(), ::landscape() ou ::letter(), então encadeie os withers. O objeto é readonly, portanto cada wither retorna uma nova instância.
• Atribua números de página reais com assignPageNumbers() a partir da sua própria passagem de layout; assignSequentialPages() produz apenas marcadores.
• entriesPerPage(), lineSpacing() e contentWidth() são derivações puras da configuração; chame-os para pré-dimensionar o layout antes de renderizar.
• getHeadings(), count() e reset() leem e limpam o estado acumulado do coletor entre varreduras.

Limite de publicação

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

Veja também

• Sumário (capacidade) — instalação, início rápido e exemplos de produção.
• Merge — Referência Profunda
• Template — Referência Profunda