跳转到内容
NextPDF
getnextpdf.com

Pro 版本

目录 — 深度参考

速览

标题为“速览”的章节

本页是 NextPDF Pro Toc 模块 NextPDF\Pro\Toc 的契约级参考。 AutoTocCollector 扫描 HTML 中的 H1–H6 标题，并发出 TocHeading 值对象。AutoTocRenderer 对这些标题分页，并将每个 TOC 页渲染为 PDF 内容流运算符。AutoTocConfig 是不可变的渲染配置。页码由调用方提供或为顺序占位符； 本模块不解析实时的文档交叉引用。本页说明公开 API、 可观察的行为契约，以及失败模式。面向任务的搭建与示例位于 目录能力页面。

可用性与授权

标题为“可用性与授权”的章节

此能力随 NextPDF Pro（nextpdf/pro）一同发布，并通过 Pro 级授权信封激活。缺少该授权的部署不会加载此能力的类。比较各版本并获取授权。

没有运行时能力标志对此模块进行门控。只要安装并授权了 nextpdf/pro，Toc 类即可使用。

公开 API 范围

标题为“公开 API 范围”的章节
符号参数默认行为返回抛出或失败于备注
AutoTocCollector::__construct()int $maxDepth = 6将深度钳制到 1–6 范围——实例累积已采集的标题
AutoTocCollector::extract()string $html, int $maxDepth = 6在一次调用中构造、扫描并返回标题list<TocHeading>—静态快捷路径
AutoTocCollector::scan()string $html匹配 H1–H6，剥去标记，解码实体，折叠空白，追加非空标题——修改内部状态
AutoTocCollector::assignSequentialPages()int $startPage = 1在首个之后的每个 level-0 标题处将页码前进list<TocHeading>—仅占位编号
AutoTocCollector::assignPageNumbers()array<int,int> $pageMap应用索引到页码的映射；未映射的索引保留其当前页码list<TocHeading>—调用方提供的真实页码
AutoTocCollector::getHeadings()—返回已采集的标题list<TocHeading>——
AutoTocCollector::count()—已采集标题的数量int——
AutoTocCollector::reset()—清除已采集的标题——在多次扫描间复用采集器
AutoTocRenderer::render()list<TocHeading> $headings, ?AutoTocConfig $config = null按深度过滤、分页、每页发出一个内容流list<string>—当所有标题都被过滤掉时返回 []
AutoTocConfig::__construct()14 个带类型的参数（标题、深度、字体、间距、边距、颜色、页面尺寸）不可变的配置载体——Readonly；ChartColor 颜色默认为黑色
AutoTocConfig::default(), ::landscape(), ::letter()—A4 纵向、A4 横向与 US Letter 预设self—静态工厂
AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()各接受一个值返回一个仅改变该字段的新实例；withMaxDepth() 钳制到 1–6self—流式，不可变
AutoTocConfig::contentWidth()—pageWidth - 2 * leftMarginfloat—派生值
AutoTocConfig::lineSpacing()—fontSize * lineHeightfloat—派生值
AutoTocConfig::entriesPerPage()—max(1, floor((pageHeight - 2*topMargin - 2*titleFontSize) / lineSpacing))int—始终 ≥ 1
TocHeading::__construct()string $title, int $level, ?int $pageNumber = null, float $y = 0.0不可变的标题值对象——Readonly；level 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()页码和/或 Y 坐标返回一个仅改变位置字段的新实例self—流式，不可变
TocHeading::hasPageNumber()—当已分配页码时为 Truebool——
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

行为契约

标题为“行为契约”的章节

采集

标题为“采集”的章节

AutoTocCollector::scan() 用一个有界模式匹配 <h1>–<h6> （不区分大小写、dot 匹配换行），该模式要求同级的开闭标签成对且平衡。每个匹配的内部内容会被剥去标签、解码实体 （ENT_QUOTES | ENT_HTML5、UTF-8），并折叠空白。空结果被丢弃。level 为标签编号减一，因此 H1 是 level 0。深于 maxDepth 的标签会被跳过。extract() 是覆盖构造、 扫描与回读的一次性工厂方法。

页码分配

标题为“页码分配”的章节

存在两种显式策略，二者均由调用方驱动。

  • assignSequentialPages($startPage) 在首个条目之后到达一个 level-0 标题时将页码计数器前进，随后为每个标题打上页码。
  • assignPageNumbers($pageMap) 应用一个索引到页码的映射；未映射的索引保留其现有页码。

两种策略都不检查已排版的文档。

渲染与分页

标题为“渲染与分页”的章节

AutoTocRenderer::render() 保留 level 低于 maxDepth 的标题， 当无一幸存时返回 []，然后将其余部分切分为大小为 AutoTocConfig::entriesPerPage() 的块。每个块成为一个内容流字符串。对每个条目，缩进为 leftMargin + level * indentPerLevel； 字号每级递减 0.5 pt，下限为 6.0 pt；level 0 使用粗体字体键，更深的层级使用常规键。当启用且存在页码时，可选的点引导线（dot leader）填补间隙，且页码右对齐。 标题与每个条目字符串均按 ISO 32000-2:2020 §9.4 用 Tj 运算符显示，且每个字符串按 §7.3.4.2 转义以符合 PDF 字面字符串语法。 相同的 HTML 与配置产出稳定的标题与运算符。

边界情况与失败模式

标题为“边界情况与失败模式”的章节
  • 格式错误的标题标记不会被采集。一个没有匹配 </h2> 的未闭合 <h2> 无法通过成对平衡模式，会被跳过。
  • 在剥去标签并修剪后为空的标题文本会被丢弃。
  • maxDepth 在采集器构造函数与 AutoTocConfig::withMaxDepth() 两处均被钳制到 1–6；越界值会被纠正，而非拒绝。
  • 页码由调用方控制。没有内部布局趟去发现标题落在的真实页面，因此本模块无法解析实时交叉引用。
  • 本模块不抛出任何异常。当所有标题都因深度被过滤掉时， render() 返回一个空数组；对空输入也从不抛出。
  • 尺寸计算会收敛到 max(1, …) 下限，因此 entriesPerPage() 始终至少为 1，且分页始终有进展。
  • 渲染器仅产出可绘制的运算符。调用方将返回的内容流放置到真实页面上，并提供 /TocFont、/TocBoldFont 与 /TocTitleFont 资源。

FIPS-mode 行为

标题为“FIPS-mode 行为”的章节

本模块中不发生任何密码学操作，因此不存在任何 FIPS-mode 特定行为。此处不消耗随机性、哈希或签名。

一致性

标题为“一致性”的章节
主张标准条款
TOC 标题与条目文本以 Tj 文本显示运算符显示ISO 32000-2:2020§9.4
发出的字符串按 PDF 字面字符串转义，反斜杠加倍且括号转义ISO 32000-2:2020§7.3.4.2
PDF /Outlines 树或命名目标（named-destination）链接—未构建（仅内容流运算符）
实时文档交叉引用解析—不支持（页码由调用方提供）

所有条款均为转述；NextPDF 不复制规范性文本。这些是能力陈述，而非认证；NextPDF 不持有任何认证， 也不授予任何认证。

开发说明

标题为“开发说明”的章节
  • Pro 包内的可用性：AutoTocCollector、AutoTocRenderer、 AutoTocConfig 与 TocHeading 自 1.9.0 起。在 nextpdf/pro 3.1.0 中全部为现行。
  • AutoTocConfig 的颜色是 NextPDF\Pro\Chart\ChartColor 值。默认的文本与标题颜色为黑色（0.0, 0.0, 0.0）。
  • 从 AutoTocConfig::default()、::landscape() 或 ::letter() 起步，然后链式调用 wither。该对象为 readonly，因此每个 wither 返回一个新实例。
  • 用你自己的布局趟通过 assignPageNumbers() 分配真实页码； assignSequentialPages() 仅产出占位符。
  • entriesPerPage()、lineSpacing() 与 contentWidth() 是配置的纯派生值；在渲染前调用它们以预先测算布局。
  • getHeadings()、count() 与 reset() 在多次扫描间读取并清除采集器累积的状态。

发布边界

标题为“发布边界”的章节

本页仅记录外部可观察的行为与受支持的公开 API 范围。内部命名空间路径、辅助类、机制表、 运行手册文件名与工单前缀均不在范围内。

另请参阅

标题为“另请参阅”的章节