Pro Edition

Inhaltsverzeichnis — Ausführliche Referenz

Auf einen Blick

Diese Seite ist die Referenz auf Vertragsebene für das NextPDF Pro-Modul Toc, NextPDF\Pro\Toc. AutoTocCollector durchsucht HTML nach H1–H6-Überschriften und gibt TocHeading-Wertobjekte aus. AutoTocRenderer paginiert diese Überschriften und stellt jede Inhaltsverzeichnisseite als PDF-Inhaltsstrom-Operatoren dar. AutoTocConfig ist die unveränderliche Darstellungskonfiguration. Seitenzahlen werden vom Aufrufer bereitgestellt oder sind fortlaufende Platzhalter; das Modul löst keine aktiven Dokument-Querverweise auf. Diese Seite legt die öffentliche API, den beobachtbaren Verhaltensvertrag und die Fehlermodi dar. Aufgabenorientierte Einrichtung und Beispiele finden Sie auf der Fähigkeitsseite Inhaltsverzeichnis.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit wird mit NextPDF Pro (nextpdf/pro) ausgeliefert und wird mit einer Lizenzhülle der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Editionen vergleichen und eine Lizenz erwerben.

Kein Laufzeit-Fähigkeitsflag schützt dieses Modul. Die Toc-Klassen sind nutzbar, sobald nextpdf/pro installiert und lizenziert ist.

Öffentliche API-Oberfläche

Symbol	Parameter	Standardverhalten	Rückgabe	Wirft oder scheitert mit	Hinweise
`AutoTocCollector::__construct()`	`int $maxDepth = 6`	Begrenzt die Tiefe auf den Bereich 1–6	—	—	Instanz sammelt die erfassten Überschriften
`AutoTocCollector::extract()`	`string $html`, `int $maxDepth = 6`	Konstruiert, durchsucht und gibt die Überschriften in einem Aufruf zurück	`list<TocHeading>`	—	Statischer Schnellpfad
`AutoTocCollector::scan()`	`string $html`	Findet H1–H6, entfernt Markup, dekodiert Entitäten, reduziert Leerraum, hängt nicht leere Überschriften an	—	—	Verändert den internen Zustand
`AutoTocCollector::assignSequentialPages()`	`int $startPage = 1`	Erhöht die Seite bei jeder Level-0-Überschrift nach der ersten	`list<TocHeading>`	—	Nur Platzhalter-Nummerierung
`AutoTocCollector::assignPageNumbers()`	`array<int,int> $pageMap`	Wendet eine Index-zu-Seite-Zuordnung an; nicht zugeordnete Indizes behalten ihre aktuelle Seite	`list<TocHeading>`	—	Vom Aufrufer bereitgestellte echte Seiten
`AutoTocCollector::getHeadings()`	—	Gibt die erfassten Überschriften zurück	`list<TocHeading>`	—	—
`AutoTocCollector::count()`	—	Anzahl der erfassten Überschriften	`int`	—	—
`AutoTocCollector::reset()`	—	Leert die erfassten Überschriften	—	—	Collector über mehrere Scans hinweg wiederverwenden
`AutoTocRenderer::render()`	`list<TocHeading> $headings`, `?AutoTocConfig $config = null`	Filtert nach Tiefe, paginiert, gibt einen Inhaltsstrom pro Seite aus	`list<string>`	—	Gibt `[]` zurück, wenn jede Überschrift herausgefiltert wird
`AutoTocConfig::__construct()`	14 typisierte Parameter (Titel, Tiefe, Schriften, Abstände, Ränder, Farben, Seitengröße)	Unveränderlicher Konfigurationsträger	—	—	Readonly; `ChartColor`-Farben sind standardmäßig schwarz
`AutoTocConfig::default(), ::landscape(), ::letter()`	—	Voreinstellungen A4 Hochformat, A4 Querformat und US Letter	`self`	—	Statische Factories
`AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()`	jeweils ein Wert	Gibt eine neue Instanz mit geändertem Feld zurück; `withMaxDepth()` begrenzt auf 1–6	`self`	—	Fluent, nicht verändernd
`AutoTocConfig::contentWidth()`	—	`pageWidth - 2 * leftMargin`	`float`	—	Abgeleitet
`AutoTocConfig::lineSpacing()`	—	`fontSize * lineHeight`	`float`	—	Abgeleitet
`AutoTocConfig::entriesPerPage()`	—	`max(1, floor((pageHeight - 2topMargin - 2titleFontSize) / lineSpacing))`	`int`	—	Immer ≥ 1
`TocHeading::__construct()`	`string $title`, `int $level`, `?int $pageNumber = null`, `float $y = 0.0`	Unveränderliches Überschriften-Wertobjekt	—	—	Readonly; Level 0 = H1
`TocHeading::withPageNumber(), ::withY(), ::withPosition()`	Seitenzahl und/oder Y-Koordinate	Gibt eine neue Instanz mit geänderten Positionsfeldern zurück	`self`	—	Fluent, nicht verändernd
`TocHeading::hasPageNumber()`	—	Wahr, wenn eine Seitenzahl zugewiesen ist	`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

Verhaltensvertrag

Erfassung

AutoTocCollector::scan() findet <h1>–<h6> mit einem begrenzten Muster (Groß-/Kleinschreibung ignorierend, Punkt erfasst Zeilenumbrüche), das ein ausgeglichenes öffnendes und schließendes Tag derselben Ebene erfordert. Der Innenraum jeder Übereinstimmung wird von Tags befreit, Entitäten werden dekodiert (ENT_QUOTES | ENT_HTML5, UTF-8) und der Leerraum wird reduziert. Leere Ergebnisse werden verworfen. level ist die Tag-Nummer minus eins, sodass H1 Level 0 ist. Ein Tag tiefer als maxDepth wird übersprungen. extract() ist die Ein-Aufruf-Factory über Konstruktion, Scan und Rücklesen.

Seitenzahlzuweisung

Es gibt zwei explizite Strategien, beide vom Aufrufer gesteuert.

assignSequentialPages($startPage) erhöht den Seitenzähler, wenn nach dem ersten Eintrag eine Level-0-Überschrift erreicht wird, und stempelt dann jede Überschrift.
assignPageNumbers($pageMap) wendet eine Index-zu-Seite-Zuordnung an; ein nicht zugeordneter Index behält seine bestehende Seitenzahl.

Keine der beiden Strategien untersucht ein umgebrochenes Dokument.

Darstellung und Paginierung

AutoTocRenderer::render() behält Überschriften, deren level unter maxDepth liegt, gibt [] zurück, wenn nichts übrig bleibt, und teilt den Rest dann in Blöcke von AutoTocConfig::entriesPerPage() auf. Jeder Block wird zu einem Inhaltsstrom-String. Pro Eintrag beträgt die Einrückung leftMargin + level * indentPerLevel; die Schriftgröße verringert sich um 0,5 pt pro Ebene und ist bei 6,0 pt begrenzt; Level 0 verwendet den Fettschrift-Key, tiefere Ebenen den regulären Key. Wenn Seitenzahlen aktiviert und vorhanden sind, füllt eine optionale Punktführung die Lücke und die Zahl wird rechtsbündig ausgerichtet. Der Titel und jeder Eintrags-String werden mit dem Tj-Operator gemäß ISO 32000-2:2020 §9.4 dargestellt, und jeder String wird für die PDF-Literal-String-Syntax gemäß §7.3.4.2 maskiert. Identisches HTML und identische Konfiguration ergeben stabile Überschriften und Operatoren.

Randfälle & Fehlermodi

Fehlerhaftes Überschriften-Markup wird nicht erfasst. Ein ungeschlossenes <h2> ohne passendes </h2> scheitert am Muster des ausgeglichenen Paares und wird übersprungen.
Überschriftentext, der nach dem Entfernen von Tags und dem Trimmen leer ist, wird verworfen.
maxDepth wird sowohl im Konstruktor des Collectors als auch bei AutoTocConfig::withMaxDepth() auf 1–6 begrenzt; Werte außerhalb des Bereichs werden korrigiert, nicht abgelehnt.
Seitenzahlen werden vom Aufrufer gesteuert. Kein interner Layoutdurchlauf ermittelt die echte Seite, auf der eine Überschrift landet, sodass das Modul keine aktiven Querverweise auflösen kann.
Das Modul löst keine Ausnahmen aus. render() gibt ein leeres Array zurück, wenn jede Überschrift durch die Tiefe herausgefiltert wird; es wirft nie bei leerer Eingabe.
Die Dimensionierung fällt auf den max(1, …)-Boden zurück, sodass entriesPerPage() immer mindestens 1 ist und die Paginierung immer fortschreitet.
Der Renderer erzeugt nur zeichenbare Operatoren. Der Aufrufer platziert die zurückgegebenen Ströme auf echten Seiten und stellt die Ressourcen /TocFont, /TocBoldFont und /TocTitleFont bereit.

Verhalten im FIPS-Modus

In diesem Modul findet keine kryptografische Operation statt, sodass kein FIPS-modusspezifisches Verhalten existiert. Nichts hier verbraucht Zufälligkeit, Hashing oder Signierung.

Konformität

Aussage	Standard	Klausel
TOC-Titel und Eintragstext mit dem Textdarstellungs-Operator `Tj` dargestellt	ISO 32000-2:2020	§9.4
Ausgegebene Strings als PDF-Literal-Strings maskiert, mit verdoppeltem Backslash und maskierten Klammern	ISO 32000-2:2020	§7.3.4.2
PDF-`/Outlines`-Baum oder Links zu benannten Zielen	—	Nicht erstellt (nur Inhaltsstrom-Operatoren)
Auflösung aktiver Dokument-Querverweise	—	Nicht unterstützt (vom Aufrufer bereitgestellte Seitenzahlen)

Alle Klauseln sind paraphrasiert; NextPDF gibt keinen normativen Text wieder. Dies sind Fähigkeitsaussagen, keine Zertifizierungen; NextPDF hält keine Zertifizierung und erteilt keine.

Entwicklungshinweise

Verfügbarkeit innerhalb des Pro-Pakets: AutoTocCollector, AutoTocRenderer, AutoTocConfig und TocHeading seit 1.9.0. Alle sind aktuell in nextpdf/pro 3.1.0.
AutoTocConfig-Farben sind NextPDF\Pro\Chart\ChartColor-Werte. Die Standard-Text- und -Titelfarben sind schwarz (0.0, 0.0, 0.0).
Beginnen Sie mit AutoTocConfig::default(), ::landscape() oder ::letter() und verketten Sie dann die Wither. Das Objekt ist readonly, sodass jeder Wither eine neue Instanz zurückgibt.
Weisen Sie echte Seitenzahlen mit assignPageNumbers() aus Ihrem eigenen Layoutdurchlauf zu; assignSequentialPages() liefert nur Platzhalter.
entriesPerPage(), lineSpacing() und contentWidth() sind reine Ableitungen der Konfiguration; rufen Sie sie auf, um das Layout vor der Darstellung vorzudimensionieren.
getHeadings(), count() und reset() lesen und leeren den angesammelten Zustand des Collectors zwischen den Scans.

Veröffentlichungsgrenze

Diese Seite dokumentiert nur extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namensraumpfade, Hilfsklassen, Mechanismustabellen, Runbook-Dateinamen und Ticket-Präfixe sind außerhalb des Geltungsbereichs.

Siehe auch

Inhaltsverzeichnis (Fähigkeit) — Installation, Schnellstart und Produktionsbeispiele.
Merge — Tiefenreferenz
Template — Ausführliche Referenz