Pro edycja

Spis treści

W skrócie

NextPDF\Pro\Toc zbiera nagłówki H1–H6 z HTML i renderuje paginowany, wielopoziomowy spis treści jako operatory strumienia treści PDF. Numery stron są dostarczane przez wywołującego (lub jako symbole zastępcze sekwencyjne); moduł nie rozwiązuje aktywnych odsyłaczy dokumentu.

Dostępność i licencjonowanie

Ta funkcja jest dostarczana w NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną tier Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Klasy Toc ładują się zawsze, gdy zainstalowany jest nextpdf/pro; żadna flaga możliwości w czasie wykonania nie bramkuje tego modułu. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Przepływ ma dwie fazy:

Zbieranie. AutoTocCollector::extract($html, maxDepth) skanuje HTML w poszukiwaniu znaczników <h1>–<h6> do limitu głębokości, pozbawia wewnętrznego znacznika, dekoduje encje, normalizuje białe znaki i emituje obiekty wartości TocHeading (poziom 0 = H1). Może przypisać sekwencyjne numery stron lub zastosować dostarczoną przez wywołującego mapę indeks-do-strony.
Renderowanie. AutoTocRenderer::render($headings, $config) wytwarza jeden łańcuch strumienia treści PDF na każdą stronę spisu treści, z wcięciem na poziom, opcjonalnymi wypełniaczami kropkowymi (dot leaders) oraz opcjonalnymi numerami stron. Każdy widoczny wiersz jest emitowany jako operacja pokazywania tekstu Tj zgodnie z ISO 32000-2:2020 §9.4.

AutoTocConfig to niemutowalny, konfigurowany płynnie (fluently) obiekt wartości sterujący tytułem, głębokością, czcionkami, odstępami, marginesami, kolorami, rozmiarem strony oraz tym, czy pokazywane są wypełniacze kropkowe i numery stron.

Dlaczego działa to w ten sposób

Kluczową decyzją jest to, że moduł nigdy nie wymyśla numeru strony, którego nie może znać. Rzeczywiste strony docelowe zależą od finalnie rozłożonego dokumentu, którego właścicielem jest wywołujący; zgadywanie dryfowałoby po cichu za każdym razem, gdy zmieniłaby się paginacja. Dlatego zbieranie i renderowanie pozostają odsprzężone od układu. AutoTocCollector emituje nagłówki ze stronami null lub zastępczymi; rzeczywiste numery stron docierają wyłącznie przez dostarczoną przez wywołującego mapę assignPageNumbers(). Renderowanie wytwarza następnie zwykłe operatory strumienia treści, pozostawiając rozmieszczenie stron wywołującemu. Wynik pozostaje deterministyczny i uczciwy: moduł podaje to, czego nie wie, zamiast to fabrykować.

Tło projektowe: API, które odmawia zgadywania.

Kontrakt zachowania

Wejście. HTML (zbieranie) oraz lista TocHeading (renderowanie).
Wyjście. list<TocHeading> ze zbierania; list<string> operatorów strumienia treści PDF (jeden na stronę spisu treści) z renderowania.
Numery stron. Przypisywane sekwencyjnie, dostarczane przez mapę indeks-do-strony lub pozostawione jako null. Moduł nie oblicza rzeczywistych stron docelowych z rozłożonego dokumentu; nie rozwiązuje odsyłaczy.
Głębokość. maxDepth jest ograniczany do 1–6. Nagłówki głębsze niż skonfigurowana głębokość są pomijane.
Determinizm. Dla identycznego HTML i konfiguracji zebrane nagłówki i wyrenderowane operatory są stabilne.

Powierzchnia publicznego API

Typ	Rodzaj	Kluczowe składowe
`NextPDF\Pro\Toc\AutoTocCollector`	`final class`	`static extract(string $html, int $maxDepth = 6): list<TocHeading>`, `scan(string $html): void`, `assignSequentialPages(int $startPage = 1): list<TocHeading>`, `assignPageNumbers(array $pageMap): list<TocHeading>`
`NextPDF\Pro\Toc\AutoTocRenderer`	`final class`	`static render(array $headings, ?AutoTocConfig $config = null): list<string>`
`NextPDF\Pro\Toc\AutoTocConfig`	`final readonly class`	`default()`, `landscape()`, `letter()`, `withTitle()`, `withMaxDepth()`, `withFontSize()`, `withDotLeader()`, `withPageNumbers()`, `withIndentPerLevel()`, `entriesPerPage(): int`
`NextPDF\Pro\Toc\TocHeading`	`final readonly class`	`string $title`, `int $level`, `?int $pageNumber`, `float $y`, `withPageNumber()`, `withPosition()`, `hasPageNumber(): bool`

Przykład kodu — Szybki start

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocRenderer;

$headings = AutoTocCollector::extract($html, maxDepth: 3);
$streams  = AutoTocRenderer::render($headings);

echo count($streams), " TOC page(s) of content-stream operators\n";

Przykład kodu — Produkcja

<?php

declare(strict_types=1);

use NextPDF\Pro\Toc\AutoTocCollector;
use NextPDF\Pro\Toc\AutoTocConfig;
use NextPDF\Pro\Toc\AutoTocRenderer;

function buildToc(string $html, array $headingPageMap): array
{
    $collector = new AutoTocCollector(maxDepth: 4);
    $collector->scan($html);

    // Caller supplies real page numbers from its own layout pass.
    $headings = $collector->assignPageNumbers($headingPageMap);

    $config = AutoTocConfig::default()
        ->withTitle('Contents')
        ->withMaxDepth(4)
        ->withDotLeader(true)
        ->withPageNumbers(true);

    return AutoTocRenderer::render($headings, $config);
}

Przypadki brzegowe i pułapki

Pusty tekst nagłówka (po pozbawieniu znaczników) jest pomijany.
maxDepth jest ograniczany do 1–6 zarówno w kolektorze, jak i w konfiguracji; wartości spoza zakresu są korygowane, a nie odrzucane.
Numery stron są symbolami zastępczymi, dopóki wywołujący nie dostarczy rzeczywistej mapy; moduł nie wykonuje przebiegu układu, aby wykryć rzeczywiste strony docelowe.
Renderer emituje operatory strumienia treści do umieszczenia na stronie; wywołujący odpowiada za dodanie tych stron do dokumentu.

Wydajność

Zbieranie to jeden przebieg wyrażenia regularnego po HTML. Renderowanie jest liniowe względem liczby nagłówków, paginowane przez entriesPerPage(). Zobacz performance_budget.

Uwagi dotyczące bezpieczeństwa

HTML jest skanowany ograniczonym wyrażeniem regularnym nagłówka z pozbawianiem znaczników; żaden HTML nie jest wykonywany i nie są podążane żadne odniesienia zewnętrzne. Wyrenderowany tekst jest escapowany do składni łańcuchów strumienia treści.

Zgodność ze standardami

Twierdzenie	Klauzula specyfikacji	Status
Wiersze spisu treści emitowane jako operacje pokazywania tekstu `Tj`	ISO 32000-2:2020 §9.4	Zweryfikowane (zestaw testów jednostkowych)
Rozwiązywanie aktywnych odsyłaczy dokumentu	—	Nieobsługiwane (numery stron dostarczane przez wywołującego)

Rozwiązanie awaryjne / alternatywa w Core

Nie ma w Core generatora spisu treści. Źródłowy HTML nagłówków zazwyczaj pochodzi z potoku HTML z Core. Zobacz /modules/core/html/.

Uwaga o granicy Enterprise

Ten moduł zbiera nagłówki i renderuje operatory spisu treści. Nie wykonuje rozwiązywania odsyłaczy w skali całego dokumentu, generowania indeksu ani synchronizacji drzewa zakładek; te kwestie są poza zakresem.

Granica publikacji

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