Inhoudsopgave — Diepe referentie

In één oogopslag

Deze pagina is de referentie op contractniveau voor de NextPDF Pro Toc-module, NextPDF\Pro\Toc. AutoTocCollector scant HTML op H1–H6-headings en produceert TocHeading-value-objects. AutoTocRenderer pagineert die headings en rendert elke TOC-pagina als PDF content-stream-operatoren. AutoTocConfig is de immutable renderingconfiguratie. Paginanummers worden door de caller aangeleverd of zijn opeenvolgende placeholders; de module resolvet geen live document-cross-references. Deze pagina beschrijft de publieke API, het waarneembare gedragscontract en de foutmodi. Taakgerichte setup en voorbeelden staan op de capaciteitspagina Inhoudsopgave.

Beschikbaarheid en licentie

Deze capaciteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelope van het Pro-niveau. Een deployment zonder die rechten laadt de klassen van de capaciteit niet. Vergelijk edities en vraag een licentie aan.

Geen runtime-capaciteitsvlag schermt deze module af. De Toc-klassen zijn bruikbaar zodra nextpdf/pro geïnstalleerd en gelicentieerd is.

Publiek API-oppervlak

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
AutoTocCollector::__construct()	int $maxDepth = 6	Klemt de diepte op het bereik 1–6	—	—	Instantie verzamelt de opgehaalde headings
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Construeert, scant en retourneert headings in één aanroep	list<TocHeading>	—	Statisch snelpad
AutoTocCollector::scan()	string $html	Matcht H1–H6, verwijdert markup, decodeert entities, klapt whitespace samen, voegt niet-lege headings toe	—	—	Muteert interne state
AutoTocCollector::assignSequentialPages()	int $startPage = 1	Verhoogt de pagina bij elke level-0-heading na de eerste	list<TocHeading>	—	Alleen placeholder-nummering
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Past een index-naar-pagina-map toe; niet-gemapte indices behouden hun huidige pagina	list<TocHeading>	—	Door caller aangeleverde echte pagina’s
AutoTocCollector::getHeadings()	—	Retourneert de opgehaalde headings	list<TocHeading>	—	—
AutoTocCollector::count()	—	Aantal opgehaalde headings	int	—	—
AutoTocCollector::reset()	—	Wist de opgehaalde headings	—	—	Hergebruik de collector over scans heen
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Filtert op diepte, pagineert, zendt één content stream per pagina uit	list<string>	—	Retourneert [] wanneer elke heading wordt weggefilterd
AutoTocConfig::__construct()	14 getypeerde params (title, depth, fonts, spacing, margins, colors, page size)	Immutable configuratiedrager	—	—	Readonly; ChartColor-kleuren zijn standaard zwart
AutoTocConfig::default(), ::landscape(), ::letter()	—	A4-portret-, A4-landschap- en US Letter-presets	self	—	Statische factories
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	één waarde elk	Retourneert een nieuwe instantie met het gewijzigde veld; withMaxDepth() klemt op 1–6	self	—	Fluent, niet-muterend
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Afgeleid
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Afgeleid
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	Altijd ≥ 1
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	Immutable heading-value-object	—	—	Readonly; level 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	paginanummer en/of Y-coördinaat	Retourneert een nieuwe instantie met gewijzigde positievelden	self	—	Fluent, niet-muterend
TocHeading::hasPageNumber()	—	True wanneer een paginanummer is toegewezen	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

Gedragscontract

Verzameling

AutoTocCollector::scan() matcht <h1>–<h6> met een begrensd patroon (hoofdletterongevoelig, dot-matches-newline) dat een gebalanceerde open- en sluittag van hetzelfde niveau vereist. De binneninhoud van elke match wordt tag-stripped, entity-decoded (ENT_QUOTES | ENT_HTML5, UTF-8) en whitespace-collapsed. Lege resultaten worden weggelaten. level is het tagnummer minus één, dus H1 is level 0. Een tag dieper dan maxDepth wordt overgeslagen. extract() is de one-call-factory over construct, scan en read-back.

Paginanummertoewijzing

Er bestaan twee expliciete strategieën, beide door de caller aangestuurd.

• assignSequentialPages($startPage) verhoogt de paginateller wanneer een level-0- heading wordt bereikt na de eerste entry, en stempelt vervolgens elke heading.
• assignPageNumbers($pageMap) past een index-naar-pagina-map toe; een niet-gemapte index behoudt zijn bestaande paginanummer.

Geen van beide strategieën inspecteert een opgemaakt document.

Rendering en paginering

AutoTocRenderer::render() behoudt headings waarvan het level onder maxDepth ligt, retourneert [] wanneer niets overblijft, en splitst de rest vervolgens in chunks van AutoTocConfig::entriesPerPage(). Elke chunk wordt één content-stream-string. Per entry is de inspringing leftMargin + level * indentPerLevel; de fontgrootte neemt 0.5 pt per level af en heeft een ondergrens van 6.0 pt; level 0 gebruikt de bold-fontsleutel, diepere levels de reguliere sleutel. Wanneer paginanummers zijn ingeschakeld en aanwezig, vult een optionele dot leader de tussenruimte en wordt het nummer rechts uitgelijnd. De titel en elke entry-string worden getoond met de Tj-operator volgens ISO 32000-2:2020 §9.4, en elke string wordt geëscaped voor PDF literal-string-syntax volgens §7.3.4.2. Identieke HTML en configuratie leveren stabiele headings en operatoren op.

Randgevallen en foutmodi

• Misvormde heading-markup wordt niet verzameld. Een niet-gesloten <h2> zonder bijbehorende </h2> faalt het balanced-pair-patroon en wordt overgeslagen.
• Heading-tekst die leeg is na tag-stripping en trimmen wordt weggelaten.
• maxDepth wordt geklemd op 1–6 bij zowel de collector-constructor als AutoTocConfig::withMaxDepth(); waarden buiten bereik worden gecorrigeerd, niet afgewezen.
• Paginanummers worden door de caller bepaald. Geen interne lay-outpass ontdekt op welke echte pagina een heading terechtkomt, dus de module kan geen live cross-references resolven.
• De module gooit geen exceptions. render() retourneert een lege array wanneer elke heading op diepte wordt weggefilterd; het gooit nooit bij lege input.
• De sizing valt terug op de max(1, …)-ondergrens, dus entriesPerPage() is altijd minstens 1 en de paginering maakt altijd voortgang.
• De renderer produceert alleen tekenbare operatoren. De caller plaatst de geretourneerde streams op echte pagina’s en levert de /TocFont-, /TocBoldFont- en /TocTitleFont-resources aan.

FIPS-modusgedrag

Er vindt geen cryptografische bewerking plaats in deze module, dus er bestaat geen FIPS-modusspecifiek gedrag. Niets hier verbruikt randomness, hashing of signing.

Conformiteit

Claim	Standaard	Clausule
TOC-titel en entry-tekst getoond met de Tj text-showing-operator	ISO 32000-2:2020	§9.4
Uitgezonden strings geëscaped als PDF literal strings, met verdubbelde backslash en geëscapete haakjes	ISO 32000-2:2020	§7.3.4.2
PDF /Outlines-boom of named-destination-links	—	Niet gebouwd (alleen content-stream-operatoren)
Live document-cross-reference-resolutie	—	Niet ondersteund (door caller aangeleverde paginanummers)

Alle clausules zijn geparafraseerd; NextPDF reproduceert geen normatieve tekst. Dit zijn capaciteitsverklaringen, geen certificeringen; NextPDF bezit geen certificering en verleent er geen.

Ontwikkelnotities

• Beschikbaarheid binnen het Pro-package: AutoTocCollector, AutoTocRenderer, AutoTocConfig en TocHeading sinds 1.9.0. Alle zijn actueel in nextpdf/pro 3.1.0.
• AutoTocConfig-kleuren zijn NextPDF\Pro\Chart\ChartColor-waarden. De standaard tekst- en titelkleuren zijn zwart (0.0, 0.0, 0.0).
• Begin bij AutoTocConfig::default(), ::landscape() of ::letter() en keten daarna withers. Het object is readonly, dus elke wither retourneert een nieuwe instantie.
• Wijs echte paginanummers toe met assignPageNumbers() vanuit je eigen lay-outpass; assignSequentialPages() levert alleen placeholders op.
• entriesPerPage(), lineSpacing() en contentWidth() zijn pure afleidingen van de config; roep ze aan om de lay-out vooraf te dimensioneren vóór het renderen.
• getHeadings(), count() en reset() lezen en wissen de opgebouwde state van de collector tussen scans.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helper-klassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixes vallen buiten de scope.

Zie ook

• Inhoudsopgave (capaciteit) — installatie, snelstart en productievoorbeelden.
• Merge — Diepe referentie
• Template — Diepe referentie