Pro 版本

此能力隨 NextPDF Pro（nextpdf/pro）出貨，並以 Pro 層級的授權封套啟用。沒有該權利的部署不會載入此能力的類別。只要安裝了 nextpdf/pro，Toc 類別即會載入；沒有任何執行階段能力旗標對此模組進行閘控。比較各版本並取得授權。

安裝

composer require nextpdf/pro:^3

概念總覽

工作流程有兩個階段：

收集。AutoTocCollector::extract($html, maxDepth) 會在 HTML 中掃描 <h1>–<h6> 標籤直到深度上限、去除內層標記、解碼實體、正規化空白，並發射 TocHeading 值物件（level 0 = H1）。它可以指派循序頁碼，或套用一個由呼叫端提供的索引到頁碼對應表。
彩現。AutoTocRenderer::render($headings, $config) 會為每個 TOC 頁面產生一個 PDF 內容串流字串，帶有依層級的縮排、選用的點狀引導線（dot leaders），以及選用的頁碼。每一個可見行都會依 ISO 32000-2:2020 §9.4 發射為一次 Tj 文字顯示作業。

AutoTocConfig 是一個不可變、以流暢式設定的值物件，控制標題、深度、字型、間距、邊界、色彩、頁面尺寸，以及是否顯示點狀引導線與頁碼。

為什麼要這樣運作

關鍵的決定是：本模組絕不憑空捏造一個它無法得知的頁碼。真正的目標頁面取決於最終排版完成的文件，而那由呼叫端所擁有；一旦分頁改變，猜測就會悄悄漂移。因此收集與彩現始終與排版解耦。AutoTocCollector 會發射帶有 null 或 placeholder 頁碼的標題；真實頁碼只會透過呼叫端提供的 assignPageNumbers() 對應表傳入。彩現接著會產生純粹的內容串流運算子，把頁面放置的工作留給呼叫端。其結果保持決定性且誠實：本模組會如實陳述它所不知道的，而非加以捏造。

設計背景：一個拒絕猜測的 API。

行為合約

**輸入。**HTML（收集）與一個 TocHeading 清單（彩現）。
**輸出。**收集得到 list<TocHeading>；彩現得到一個 PDF 內容串流運算子的 list<string>（每個 TOC 頁面一個）。
**頁碼。**可循序指派、透過一個索引到頁碼對應表提供，或留為 null。本模組不會從一份已排版的文件計算真實的目標頁面；它不會解析交叉參照。
深度。maxDepth 會被鉗制在 1–6。深於所設定深度的標題會被略過。
**決定性。**對於相同的 HTML 與設定，所收集的標題與所彩現的運算子是穩定的。

公開 API 介面

型別	種類	主要成員
`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`

程式碼範例——快速上手

<?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";

程式碼範例——正式環境

<?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);
}

邊界案例與陷阱

空白的標題文字（在去除標籤後）會被略過。
maxDepth 在收集器與設定兩處都會被鉗制在 1–6；超出範圍的值會被修正，而非被拒絕。
除非呼叫端提供一個真實的對應表，否則頁碼是 placeholder；本模組不會執行一個排版過程以探查真實的目標頁面。
彩現器會發射內容串流運算子，以供放置到一個頁面上；呼叫端負責將那些頁面加入文件。

效能

收集是對 HTML 進行的一次正規表示式掃描。彩現在標題數量上呈線性，並由 entriesPerPage() 分頁。請參閱 performance_budget。

安全注意事項

HTML 會以一個有界的標題正規表示式與標籤去除進行掃描；不執行任何 HTML，也不追蹤任何外部參照。已彩現的文字會為內容串流字串語法進行轉義。

一致性

聲明	規範條款	狀態
TOC 各行發射為 `Tj` 文字顯示作業	ISO 32000-2:2020 §9.4	已驗證（單元測試套件）
即時文件交叉參照解析	—	不支援（由呼叫端提供頁碼）

Core 回退/替代方案

沒有 Core TOC 產生器。標題來源 HTML 通常來自 Core HTML 管線。請參閱 /modules/core/html/。

Enterprise 邊界註記

本模組收集標題並彩現 TOC 運算子。它不執行文件範圍的交叉參照解析、索引產生，或書籤樹同步；那些範疇不在本模組範圍內。

發佈邊界

本頁僅記載外部可觀察的行為與所支援的公開 API 介面。內部命名空間路徑、輔助類別、機制表格、runbook 檔名，以及工單前綴皆不在範圍內。

目錄

速覽

可用性與授權

安裝