Table of contents — Riferimento approfondito

In sintesi

Questa pagina è il riferimento a livello di contratto per il modulo Toc di NextPDF Pro, NextPDF\Pro\Toc. AutoTocCollector esegue la scansione dell’HTML alla ricerca delle intestazioni H1–H6 ed emette value object TocHeading. AutoTocRenderer impagina tali intestazioni e renderizza ogni pagina del TOC come operatori di content stream PDF. AutoTocConfig è la configurazione di rendering immutabile. I numeri di pagina sono forniti dal chiamante oppure sono segnaposto sequenziali; il modulo non risolve i riferimenti incrociati live del documento. Questa pagina definisce l’API pubblica, il contratto di comportamento osservabile e le modalità di errore. La configurazione orientata alle attività e gli esempi si trovano nella pagina della funzionalità Table of contents.

Disponibilità e licenze

Questa funzionalità è inclusa in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Confronta le edizioni e ottieni una licenza.

Nessun flag di capability di runtime applica il gate a questo modulo. Le classi Toc sono utilizzabili ogniqualvolta nextpdf/pro è installato e provvisto di licenza.

Superficie API pubblica

Simbolo	Parametri	Comportamento predefinito	Restituisce	Solleva o fallisce con	Note
AutoTocCollector::__construct()	int $maxDepth = 6	Limita la profondità all’intervallo 1–6	—	—	L’istanza accumula le intestazioni raccolte
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Costruisce, esegue la scansione e restituisce le intestazioni in un’unica chiamata	list<TocHeading>	—	Percorso rapido statico
AutoTocCollector::scan()	string $html	Corrisponde a H1–H6, rimuove il markup, decodifica le entità, compatta gli spazi, aggiunge le intestazioni non vuote	—	—	Modifica lo stato interno
AutoTocCollector::assignSequentialPages()	int $startPage = 1	Avanza di pagina a ogni intestazione di livello 0 dopo la prima	list<TocHeading>	—	Solo numerazione segnaposto
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Applica una mappa indice-pagina; gli indici non mappati mantengono la pagina corrente	list<TocHeading>	—	Pagine reali fornite dal chiamante
AutoTocCollector::getHeadings()	—	Restituisce le intestazioni raccolte	list<TocHeading>	—	—
AutoTocCollector::count()	—	Numero di intestazioni raccolte	int	—	—
AutoTocCollector::reset()	—	Cancella le intestazioni raccolte	—	—	Riutilizzare il collector tra più scansioni
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Filtra per profondità, impagina, emette un content stream per pagina	list<string>	—	Restituisce [] quando tutte le intestazioni vengono filtrate
AutoTocConfig::__construct()	14 parametri tipizzati (title, depth, fonts, spacing, margins, colors, page size)	Contenitore di configurazione immutabile	—	—	Readonly; i colori ChartColor sono neri per impostazione predefinita
AutoTocConfig::default(), ::landscape(), ::letter()	—	Preset A4 verticale, A4 orizzontale e US Letter	self	—	Factory statiche
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	un valore ciascuno	Restituisce una nuova istanza con il campo modificato; withMaxDepth() limita a 1–6	self	—	Fluent, non mutante
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Derivato
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Derivato
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	Value object di intestazione immutabile	—	—	Readonly; level 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	numero di pagina e/o coordinata Y	Restituisce una nuova istanza con i campi di posizione modificati	self	—	Fluent, non mutante
TocHeading::hasPageNumber()	—	True quando è assegnato un numero di pagina	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

Contratto di comportamento

Raccolta

AutoTocCollector::scan() corrisponde a <h1>–<h6> con un pattern delimitato (senza distinzione tra maiuscole e minuscole, con il punto che corrisponde anche al newline) che richiede un tag di apertura e chiusura bilanciato dello stesso livello. Il contenuto interno di ciascuna corrispondenza viene privato dei tag, decodificato dalle entità (ENT_QUOTES | ENT_HTML5, UTF-8) e con gli spazi compattati. I risultati vuoti vengono scartati. level è il numero del tag meno uno, quindi H1 è il livello 0. Un tag più profondo di maxDepth viene ignorato. extract() è la factory in una sola chiamata su costruzione, scansione e lettura.

Assegnazione dei numeri di pagina

Esistono due strategie esplicite, entrambe guidate dal chiamante.

• assignSequentialPages($startPage) avanza il contatore di pagina quando viene raggiunta un’intestazione di livello 0 dopo la prima voce, quindi marca ogni intestazione.
• assignPageNumbers($pageMap) applica una mappa indice-pagina; un indice non mappato mantiene il proprio numero di pagina esistente.

Nessuna delle due strategie ispeziona un documento già impaginato.

Rendering e impaginazione

AutoTocRenderer::render() conserva le intestazioni il cui level è inferiore a maxDepth, restituisce [] quando non ne sopravvive nessuna, quindi suddivide il resto in blocchi di AutoTocConfig::entriesPerPage(). Ogni blocco diventa una stringa di content stream. Per ciascuna voce, l’indentazione è leftMargin + level * indentPerLevel; la dimensione del font diminuisce di 0.5 pt per livello ed è limitata a un minimo di 6.0 pt; il livello 0 usa la chiave del font in grassetto, i livelli più profondi la chiave regolare. Quando i numeri di pagina sono abilitati e presenti, un dot leader opzionale riempie lo spazio e il numero viene allineato a destra. Il titolo e ogni stringa di voce vengono visualizzati con l’operatore Tj secondo ISO 32000-2:2020 §9.4, e ogni stringa viene sottoposta a escape per la sintassi delle stringhe letterali PDF secondo §7.3.4.2. HTML e configurazione identici producono intestazioni e operatori stabili.

Casi limite e modalità di errore

• Il markup di intestazione malformato non viene raccolto. Un <h2> non chiuso senza il corrispondente </h2> non supera il pattern a coppia bilanciata e viene ignorato.
• Il testo di intestazione vuoto dopo la rimozione dei tag e il trimming viene scartato.
• maxDepth è limitato all’intervallo 1–6 sia nel costruttore del collector sia in AutoTocConfig::withMaxDepth(); i valori fuori intervallo vengono corretti, non rifiutati.
• I numeri di pagina sono controllati dal chiamante. Nessuna passata di layout interna individua la pagina reale su cui cade un’intestazione, pertanto il modulo non può risolvere i riferimenti incrociati live.
• Il modulo non solleva eccezioni. render() restituisce un array vuoto quando tutte le intestazioni vengono filtrate per profondità; non solleva mai eccezioni su input vuoto.
• Il dimensionamento si riduce al minimo max(1, …), quindi entriesPerPage() è sempre almeno 1 e l’impaginazione avanza sempre.
• Il renderer produce solo operatori disegnabili. Il chiamante colloca gli stream restituiti su pagine reali e fornisce le risorse /TocFont, /TocBoldFont e /TocTitleFont.

Comportamento in modalità FIPS

In questo modulo non si verifica alcuna operazione crittografica, pertanto non esiste alcun comportamento specifico della modalità FIPS. Nulla qui utilizza casualità, hashing o firma.

Conformità

Affermazione	Standard	Clausola
Titolo del TOC e testo delle voci visualizzati con l’operatore di visualizzazione del testo Tj	ISO 32000-2:2020	§9.4
Stringhe emesse sottoposte a escape come stringhe letterali PDF, con backslash raddoppiato e parentesi sottoposte a escape	ISO 32000-2:2020	§7.3.4.2
Albero PDF /Outlines o link a destinazioni nominate	—	Non costruito (solo operatori di content stream)
Risoluzione dei riferimenti incrociati live del documento	—	Non supportata (numeri di pagina forniti dal chiamante)

Tutte le clausole sono parafrasate; NextPDF non riproduce il testo normativo. Si tratta di dichiarazioni di funzionalità, non di certificazioni; NextPDF non detiene alcuna certificazione e non ne concede alcuna.

Note di sviluppo

• Disponibilità all’interno del pacchetto Pro: AutoTocCollector, AutoTocRenderer, AutoTocConfig e TocHeading a partire dalla 1.9.0. Tutti sono attuali in nextpdf/pro 3.1.0.
• I colori di AutoTocConfig sono valori NextPDF\Pro\Chart\ChartColor. I colori predefiniti del testo e del titolo sono neri (0.0, 0.0, 0.0).
• Partire da AutoTocConfig::default(), ::landscape() o ::letter(), quindi concatenare i wither. L’oggetto è readonly, quindi ogni wither restituisce una nuova istanza.
• Assegnare numeri di pagina reali con assignPageNumbers() a partire dalla propria passata di layout; assignSequentialPages() produce solo segnaposto.
• entriesPerPage(), lineSpacing() e contentWidth() sono derivazioni pure della configurazione; richiamarle per pre-dimensionare il layout prima del rendering.
• getHeadings(), count() e reset() leggono e cancellano lo stato accumulato del collector tra le scansioni.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile esternamente e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle dei meccanismi, nomi di file dei runbook e prefissi dei ticket sono fuori ambito.

Vedere anche

• Table of contents (funzionalità) — installazione, avvio rapido ed esempi di produzione.
• Merge — Riferimento approfondito
• Template — Riferimento approfondito