Spis treści — pełna dokumentacja referencyjna

W skrócie

Ta strona jest dokumentacją na poziomie kontraktu dla modułu Toc w NextPDF Pro, NextPDF\Pro\Toc. AutoTocCollector skanuje HTML w poszukiwaniu nagłówków H1–H6 i emituje obiekty wartości TocHeading. AutoTocRenderer paginuje te nagłówki i renderuje każdą stronę spisu treści jako operatory strumienia treści PDF. AutoTocConfig to niezmienna konfiguracja renderowania. Numery stron są dostarczane przez wywołującego lub stanowią sekwencyjne wypełniacze; moduł nie rozwiązuje aktywnych odsyłaczy w dokumencie. Ta strona opisuje publiczne API, obserwowalny kontrakt zachowania oraz tryby awarii. Konfiguracja zadaniowa i przykłady znajdują się na stronie możliwości Spis treści.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Porównaj edycje i uzyskaj licencję.

Żadna flaga możliwości w czasie wykonania nie bramkuje tego modułu. Klasy Toc są używalne zawsze, gdy nextpdf/pro jest zainstalowany i licencjonowany.

Powierzchnia publicznego API

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się niepowodzeniem	Uwagi
AutoTocCollector::__construct()	int $maxDepth = 6	Ogranicza głębokość do zakresu 1–6	—	—	Instancja gromadzi zebrane nagłówki
AutoTocCollector::extract()	string $html, int $maxDepth = 6	Konstruuje, skanuje i zwraca nagłówki w jednym wywołaniu	list<TocHeading>	—	Statyczna szybka ścieżka
AutoTocCollector::scan()	string $html	Dopasowuje H1–H6, usuwa znaczniki, dekoduje encje, redukuje białe znaki, dołącza niepuste nagłówki	—	—	Modyfikuje stan wewnętrzny
AutoTocCollector::assignSequentialPages()	int $startPage = 1	Przesuwa stronę przy każdym nagłówku poziomu 0 po pierwszym	list<TocHeading>	—	Wyłącznie numeracja zastępcza
AutoTocCollector::assignPageNumbers()	array<int,int> $pageMap	Stosuje mapę indeks-do-strony; niezmapowane indeksy zachowują bieżącą stronę	list<TocHeading>	—	Rzeczywiste strony dostarczane przez wywołującego
AutoTocCollector::getHeadings()	—	Zwraca zebrane nagłówki	list<TocHeading>	—	—
AutoTocCollector::count()	—	Liczba zebranych nagłówków	int	—	—
AutoTocCollector::reset()	—	Czyści zebrane nagłówki	—	—	Ponowne użycie kolektora między skanowaniami
AutoTocRenderer::render()	list<TocHeading> $headings, ?AutoTocConfig $config = null	Filtruje według głębokości, paginuje, emituje jeden strumień treści na stronę	list<string>	—	Zwraca [], gdy wszystkie nagłówki zostaną odfiltrowane
AutoTocConfig::__construct()	14 typowanych parametrów (tytuł, głębokość, czcionki, odstępy, marginesy, kolory, rozmiar strony)	Niezmienny nośnik konfiguracji	—	—	Readonly; kolory ChartColor domyślnie czarne
AutoTocConfig::default(), ::landscape(), ::letter()	—	Ustawienia A4 pionowo, A4 poziomo oraz US Letter	self	—	Statyczne fabryki
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()	po jednej wartości	Zwraca nową instancję ze zmienionym polem; withMaxDepth() ogranicza do 1–6	self	—	Płynne, bez mutacji
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Pochodne
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Pochodne
AutoTocConfig::entriesPerPage()	—	max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))	int	—	Zawsze ≥ 1
TocHeading::__construct()	string $title, int $level, ?int $pageNumber = null, float $y = 0.0	Niezmienny obiekt wartości nagłówka	—	—	Readonly; poziom 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	numer strony i/lub współrzędna Y	Zwraca nową instancję ze zmienionymi polami pozycji	self	—	Płynne, bez mutacji
TocHeading::hasPageNumber()	—	Prawda, gdy przypisano numer strony	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

Kontrakt zachowania

Zbieranie

AutoTocCollector::scan() dopasowuje <h1>–<h6> ograniczonym wzorcem (bez rozróżniania wielkości liter, z dopasowywaniem nowego wiersza przez kropkę), który wymaga zbalansowanego znacznika otwierającego i zamykającego tego samego poziomu. Treść wewnętrzna każdego dopasowania jest pozbawiana znaczników, dekodowana z encji (ENT_QUOTES | ENT_HTML5, UTF-8) i pozbawiana nadmiarowych białych znaków. Puste wyniki są odrzucane. level to numer znacznika minus jeden, więc H1 ma poziom 0. Znacznik głębszy niż maxDepth jest pomijany. extract() to jednowywołaniowa fabryka łącząca konstrukcję, skanowanie i odczyt.

Przypisanie numeracji stron

Istnieją dwie jawne strategie, obie sterowane przez wywołującego.

• assignSequentialPages($startPage) przesuwa licznik stron, gdy po pierwszym wpisie zostaje osiągnięty nagłówek poziomu 0, a następnie stempluje każdy nagłówek.
• assignPageNumbers($pageMap) stosuje mapę indeks-do-strony; niezmapowany indeks zachowuje swój istniejący numer strony.

Żadna ze strategii nie analizuje rozłożonego dokumentu.

Renderowanie i paginacja

AutoTocRenderer::render() zachowuje nagłówki, których level jest mniejszy niż maxDepth, zwraca [], gdy nic nie pozostaje, a następnie dzieli resztę na porcje po AutoTocConfig::entriesPerPage(). Każda porcja staje się jednym łańcuchem strumienia treści. Dla każdego wpisu wcięcie wynosi leftMargin + level * indentPerLevel; rozmiar czcionki zmniejsza się o 0.5 pt na poziom i jest ograniczony od dołu do 6.0 pt; poziom 0 używa klucza czcionki pogrubionej, głębsze poziomy klucza zwykłego. Gdy numery stron są włączone i obecne, opcjonalny wypełniacz z kropek wypełnia przerwę, a numer jest wyrównany do prawej. Tytuł oraz każdy łańcuch wpisu są pokazywane operatorem Tj zgodnie z ISO 32000-2:2020 §9.4, a każdy łańcuch jest poddawany sekwencjom ucieczki dla składni łańcuchów literalnych PDF zgodnie z §7.3.4.2. Identyczny HTML i konfiguracja dają stabilne nagłówki i operatory.

Przypadki brzegowe i tryby awarii

• Błędnie sformułowany znacznik nagłówka nie jest zbierany. Niezamknięty <h2> bez pasującego </h2> nie spełnia wzorca zbalansowanej pary i jest pomijany.
• Tekst nagłówka, który jest pusty po usunięciu znaczników i przycięciu, jest odrzucany.
• maxDepth jest ograniczany do 1–6 zarówno w konstruktorze kolektora, jak i w AutoTocConfig::withMaxDepth(); wartości spoza zakresu są korygowane, a nie odrzucane.
• Numery stron są kontrolowane przez wywołującego. Żaden wewnętrzny przebieg układu nie wykrywa rzeczywistej strony, na której ląduje nagłówek, więc moduł nie potrafi rozwiązywać aktywnych odsyłaczy.
• Moduł nie zgłasza żadnych wyjątków. render() zwraca pustą tablicę, gdy wszystkie nagłówki zostaną odfiltrowane według głębokości; nigdy nie zgłasza wyjątku przy pustym wejściu.
• Wymiarowanie redukuje się do dolnej granicy max(1, …), więc entriesPerPage() zawsze wynosi co najmniej 1, a paginacja zawsze postępuje.
• Renderer wytwarza wyłącznie rysowalne operatory. Wywołujący umieszcza zwrócone strumienie na rzeczywistych stronach i dostarcza zasoby /TocFont, /TocBoldFont oraz /TocTitleFont.

Zachowanie w trybie FIPS

W tym module nie zachodzi żadna operacja kryptograficzna, więc nie istnieje żadne zachowanie specyficzne dla trybu FIPS. Nic tutaj nie korzysta z losowości, haszowania ani podpisywania.

Zgodność ze standardami

Twierdzenie	Standard	Klauzula
Tytuł spisu treści i tekst wpisów pokazywane operatorem pokazywania tekstu Tj	ISO 32000-2:2020	§9.4
Emitowane łańcuchy poddane ucieczce jako łańcuchy literalne PDF, z podwojonym ukośnikiem wstecznym i nawiasami poddanymi ucieczce	ISO 32000-2:2020	§7.3.4.2
Drzewo /Outlines PDF lub odnośniki do nazwanych miejsc docelowych	—	Nie budowane (wyłącznie operatory strumienia treści)
Rozwiązywanie aktywnych odsyłaczy w dokumencie	—	Nieobsługiwane (numery stron dostarczane przez wywołującego)

Wszystkie klauzule są sparafrazowane; NextPDF nie odtwarza tekstu normatywnego. Są to deklaracje możliwości, a nie certyfikaty; NextPDF nie posiada żadnej certyfikacji ani żadnej nie udziela.

Uwagi deweloperskie

• Dostępność w pakiecie Pro: AutoTocCollector, AutoTocRenderer, AutoTocConfig oraz TocHeading od 1.9.0. Wszystkie są aktualne w nextpdf/pro 3.1.0.
• Kolory AutoTocConfig to wartości NextPDF\Pro\Chart\ChartColor. Domyślne kolory tekstu i tytułu są czarne (0.0, 0.0, 0.0).
• Zacznij od AutoTocConfig::default(), ::landscape() lub ::letter(), a następnie łańcuchowo wywołuj metody wither. Obiekt jest readonly, więc każda metoda wither zwraca nową instancję.
• Przypisuj rzeczywiste numery stron za pomocą assignPageNumbers() z własnego przebiegu układu; assignSequentialPages() daje wyłącznie wartości zastępcze.
• entriesPerPage(), lineSpacing() oraz contentWidth() to czyste pochodne konfiguracji; wywołuj je, aby wstępnie zwymiarować układ przed renderowaniem.
• getHeadings(), count() oraz reset() odczytują i czyszczą zgromadzony stan kolektora między skanowaniami.

Granica publikacji

Ta strona dokumentuje wyłącznie zewnętrznie obserwowalne zachowanie i wspieraną powierzchnię publicznego API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbook oraz prefiksy zgłoszeń są poza zakresem.

Zobacz także

• Spis treści (możliwość) — instalacja, szybki start i przykłady produkcyjne.
• Merge — pełna dokumentacja referencyjna
• Template — pełna dokumentacja referencyjna