Оглавление — глубокий справочник

Кратко

Эта страница — справочник уровня контракта по модулю NextPDF Pro Toc, NextPDF\Pro\Toc. AutoTocCollector сканирует HTML на заголовки H1–H6 и выдаёт value-объекты TocHeading. AutoTocRenderer разбивает эти заголовки на страницы и отрисовывает каждую страницу оглавления как операторы потока содержимого PDF. AutoTocConfig — это неизменяемая конфигурация отрисовки. Номера страниц предоставляются вызывающей стороной или являются последовательными заполнителями; модуль не разрешает живые перекрёстные ссылки документа. Эта страница описывает публичный API, контракт наблюдаемого поведения и режимы сбоев. Ориентированные на задачи настройка и примеры находятся на странице возможности «Оглавление».

Доступность и лицензирование

Эта возможность поставляется в NextPDF Pro (nextpdf/pro) и активируется лицензионным конвертом уровня Pro. Развёртывание без этого права не загружает классы возможности. Сравните редакции и получите лицензию.

Никакой флаг возможности времени выполнения не гейтирует этот модуль. Классы Toc доступны всегда, когда nextpdf/pro установлен и лицензирован.

Поверхность публичного 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	Увеличивает страницу на каждом заголовке уровня 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–6	self	—	Текучий, без мутаций
AutoTocConfig::contentWidth()	—	pageWidth - 2 * leftMargin	float	—	Производное
AutoTocConfig::lineSpacing()	—	fontSize * lineHeight	float	—	Производное
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	Неизменяемый value-объект заголовка	—	—	Readonly; уровень 0 = H1
TocHeading::withPageNumber(), ::withY(), ::withPosition()	номер страницы и/или координата Y	Возвращает новый экземпляр с изменёнными полями позиции	self	—	Текучий, без мутаций
TocHeading::hasPageNumber()	—	True, когда назначен номер страницы	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

Контракт поведения

Сбор

AutoTocCollector::scan() сопоставляет <h1>–<h6> ограниченным шаблоном (без учёта регистра, точка совпадает с переводом строки), который требует сбалансированной пары открывающего и закрывающего тегов одного уровня. Внутреннее содержимое каждого совпадения очищается от тегов, декодируется из сущностей (ENT_QUOTES | ENT_HTML5, UTF-8) и сворачивается по пробелам. Пустые результаты отбрасываются. level — это номер тега минус один, поэтому H1 имеет уровень 0. Тег глубже maxDepth пропускается. extract() — это фабрика в один вызов над созданием, сканированием и считыванием.

Назначение номеров страниц

Существуют две явные стратегии, обе управляются вызывающей стороной.

• assignSequentialPages($startPage) увеличивает счётчик страниц, когда после первой записи достигается заголовок уровня 0, затем проставляет номер каждому заголовку.
• assignPageNumbers($pageMap) применяет карту «индекс → страница»; несопоставленный индекс сохраняет свой текущий номер страницы.

Ни одна из стратегий не анализирует скомпонованный документ.

Отрисовка и разбивка на страницы

AutoTocRenderer::render() сохраняет заголовки, чей level меньше maxDepth, возвращает [], когда ничего не остаётся, затем разбивает остаток на порции по AutoTocConfig::entriesPerPage(). Каждая порция становится одной строкой потока содержимого. Для каждой записи отступ равен leftMargin + level * indentPerLevel; размер шрифта уменьшается на 0.5 pt на уровень и ограничивается снизу значением 6.0 pt; уровень 0 использует ключ жирного шрифта, более глубокие уровни — обычный ключ. Когда номера страниц включены и присутствуют, необязательный точечный заполнитель заполняет промежуток, а номер выравнивается по правому краю. Заголовок и каждая строка записи показываются оператором Tj согласно ISO 32000-2:2020 §9.4, и каждая строка экранируется для синтаксиса литеральных строк PDF согласно §7.3.4.2. Идентичные HTML и конфигурация дают стабильные заголовки и операторы.

Граничные случаи и режимы сбоев

• Некорректная разметка заголовка не собирается. Незакрытый <h2> без соответствующего </h2> не проходит шаблон сбалансированной пары и пропускается.
• Текст заголовка, пустой после удаления тегов и обрезки, отбрасывается.
• maxDepth зажимается в 1–6 как в конструкторе сборщика, так и в AutoTocConfig::withMaxDepth(); значения вне диапазона исправляются, а не отклоняются.
• Номера страниц управляются вызывающей стороной. Внутреннего прохода компоновки, который обнаруживает реальную страницу попадания заголовка, нет, поэтому модуль не может разрешать живые перекрёстные ссылки.
• Модуль не выбрасывает исключений. render() возвращает пустой массив, когда все заголовки отфильтрованы по глубине; он никогда не бросает на пустом вводе.
• Расчёт размера сворачивается к нижней границе max(1, …), поэтому entriesPerPage() всегда не менее 1, и разбивка на страницы всегда продвигается.
• Отрисовщик создаёт только рисуемые операторы. Вызывающая сторона размещает возвращённые потоки на реальных страницах и предоставляет ресурсы /TocFont, /TocBoldFont и /TocTitleFont.

Поведение в режиме FIPS

В этом модуле не происходит криптографических операций, поэтому поведения, специфичного для режима FIPS, нет. Ничто здесь не использует случайность, хеширование или подпись.

Соответствие

Утверждение	Стандарт	Пункт
Заголовок оглавления и текст записей показываются оператором показа текста Tj	ISO 32000-2:2020	§9.4
Эмитируемые строки экранируются как литеральные строки PDF, с удвоением обратной косой черты и экранированием скобок	ISO 32000-2:2020	§7.3.4.2
Дерево PDF /Outlines или ссылки на именованные назначения	—	Не строится (только операторы потока содержимого)
Разрешение живых перекрёстных ссылок документа	—	Не поддерживается (номера страниц от вызывающей стороны)

Все пункты пересказаны; 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(), затем сцепляйте withers. Объект readonly, поэтому каждый wither возвращает новый экземпляр.
• Назначайте реальные номера страниц через assignPageNumbers() из собственного прохода компоновки; assignSequentialPages() даёт только заполнители.
• entriesPerPage(), lineSpacing() и contentWidth() — это чистые производные конфигурации; вызывайте их для предварительного расчёта размеров компоновки перед отрисовкой.
• getHeadings(), count() и reset() считывают и очищают накопленное состояние сборщика между сканированиями.

Граница публикации

Эта страница документирует только внешне наблюдаемое поведение и поддерживаемую поверхность публичного API. Внутренние пути пространств имён, вспомогательные классы, таблицы механизмов, имена файлов runbook и префиксы тикетов вне области рассмотрения.

См. также

• Оглавление (возможность) — установка, быстрый старт и рабочие примеры.
• Merge — углублённый справочник
• Template — глубокий справочник