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 或占位页码；真实页码只经由调用方提供的 assignPageNumbers() 映射到来。随后渲染只产出朴素的内容流运算符，将页面放置留给调用方。其结果保持确定且诚实：本模块声明它不知道的内容，而非伪造它。

设计背景：一个拒绝猜测的 API。

行为契约

输入。 HTML（收集）和一个 TocHeading 列表（渲染）。
输出。 收集得到 list<TocHeading>；渲染得到一个 PDF 内容流运算符的 list<string>（每个 TOC 页面一个）。
页码。 既可顺序分配，也可经由一个索引到页码映射提供，或保留为 null。本模块不从一份已排版的文档计算真实的目标页面；它不解析交叉引用。
深度。 maxDepth 被钳制到 1–6。比所配置深度更深的标题会被跳过。
确定性。 对于相同的 HTML 与配置，所收集的标题与渲染出的运算符是稳定的。

公开 API 范围

Type	Kind	Key members
`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；超出范围的值会被纠正，而非被拒绝。
除非调用方提供一个真实的映射，否则页码是占位符；本模块不运行布局趟来发现真实的目标页面。
渲染器发出用于放置到页面上的内容流运算符；调用方负责将那些页面添加到文档。

性能

收集是对 HTML 的一次正则表达式趟。渲染在标题数量上呈线性，并按 entriesPerPage() 分页。参见 performance_budget。

安全说明

HTML 用一个有界的标题正则表达式与标签剥离扫描；不执行任何 HTML，也不跟踪任何外部引用。渲染出的文本按内容流字符串语法转义。

一致性

Claim	Spec clause	Status
TOC 行作为 `Tj` 文本显示操作发出	ISO 32000-2:2020 §9.4	已验证（单元套件）
实时文档交叉引用解析	—	不支持（调用方提供的页码）

Core 回退/替代方案

不存在 Core TOC 生成器。标题源 HTML 通常来自 Core HTML 管线。参见 /modules/core/html/。

Enterprise 边界说明

本模块收集标题并渲染 TOC 运算符。它不执行全文档范围的交叉引用解析、索引生成或书签树同步；那些关注点超出范围。

发布边界

本页仅描述外部可观测行为与所支持的公开 API 范围。内部命名空间路径、辅助类、机制表、运维手册文件名以及工单前缀均超出范围。

目录

速览

可用性与授权

安装