Pro エディション

Table of contents — 詳細リファレンス

概要

このページは、NextPDF Pro Toc モジュール NextPDF\Pro\Toc のコントラクトレベルリファレンスです。AutoTocCollector は HTML から H1–H6 の見出しをスキャンし、TocHeading 値オブジェクトを出力します。AutoTocRenderer はそれらの見出しをページ分割し、各 TOC ページを PDF コンテンツストリーム演算子としてレンダリングします。AutoTocConfig はイミュータブルなレンダリング設定です。ページ番号は呼び出し元が指定するか、順次のプレースホルダーであり、モジュールはライブなドキュメントの相互参照を解決しません。このページでは、公開 API、観測可能な挙動コントラクト、そして障害モードを述べます。タスク指向のセットアップとサンプルは、Table of contents 機能ページにあります。

提供状況とライセンス

この機能は NextPDF Pro（nextpdf/pro）に同梱され、Pro ティアのライセンスエンベロープで有効化されます。そのエンタイトルメントを持たないデプロイでは、この機能のクラスはロードされません。エディションを比較してライセンスを入手する。

このモジュールをゲートするランタイム機能フラグはありません。Toc クラスは nextpdf/pro がインストールされライセンスされている限り、いつでも利用できます。

公開 API サーフェス

シンボル	パラメーター	デフォルトの挙動	戻り値	スロー/失敗の内容	備考
`AutoTocCollector::__construct()`	`int $maxDepth = 6`	深さを 1–6 の範囲にクランプ	—	—	インスタンスは収集した見出しを蓄積
`AutoTocCollector::extract()`	`string $html`, `int $maxDepth = 6`	構築・スキャン・見出しの返却を 1 回の呼び出しで実行	`list<TocHeading>`	—	静的なファストパス
`AutoTocCollector::scan()`	`string $html`	H1–H6 にマッチし、マークアップを除去、エンティティをデコード、空白を折りたたみ、空でない見出しを追加	—	—	内部状態を変更
`AutoTocCollector::assignSequentialPages()`	`int $startPage = 1`	最初のレベル 0 見出し以降、各レベル 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`	深さでフィルタリングし、ページ分割し、ページごとに 1 つのコンテンツストリームを出力	`list<string>`	—	すべての見出しが除外されると `[]` を返す
`AutoTocConfig::__construct()`	14 個の型付きパラメーター（title、depth、fonts、spacing、margins、colors、page size）	イミュータブルな設定キャリア	—	—	readonly。`ChartColor` の色はデフォルトで黒
`AutoTocConfig::default(), ::landscape(), ::letter()`	—	A4 縦、A4 横、US Letter のプリセット	`self`	—	静的ファクトリ
`AutoTocConfig::withTitle(), ::withMaxDepth(), ::withFontSize(), ::withDotLeader(), ::withPageNumbers(), ::withIndentPerLevel()`	それぞれ 1 つの値	該当フィールドを変更した新しいインスタンスを返す。`withMaxDepth()` は 1–6 にクランプ	`self`	—	流暢、非破壊
`AutoTocConfig::contentWidth()`	—	`pageWidth - 2 * leftMargin`	`float`	—	派生値
`AutoTocConfig::lineSpacing()`	—	`fontSize * lineHeight`	`float`	—	派生値
`AutoTocConfig::entriesPerPage()`	—	`max(1, floor((pageHeight - 2topMargin - 2titleFontSize) / lineSpacing))`	`int`	—	常に 1 以上
`TocHeading::__construct()`	`string $title`, `int $level`, `?int $pageNumber = null`, `float $y = 0.0`	イミュータブルな見出し値オブジェクト	—	—	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 はタグ番号から 1 を引いた値であり、H1 はレベル 0 です。maxDepth より深いタグはスキップされます。extract() は、構築・スキャン・読み戻しをまとめた 1 回呼び出しのファクトリです。

ページ番号の割り当て

明示的なストラテジーが 2 つあり、いずれも呼び出し元が駆動します。

assignSequentialPages($startPage) は、最初のエントリの後にレベル 0 の見出しに到達したときにページカウンターを進め、その後すべての見出しにスタンプします。
assignPageNumbers($pageMap) は、インデックスからページへのマップを適用します。マップされないインデックスは既存のページ番号を維持します。

どちらのストラテジーも、レイアウト済みのドキュメントを検査しません。

レンダリングとページネーション

AutoTocRenderer::render() は level が maxDepth 未満の見出しを保持し、残るものがなければ [] を返し、その後残りを AutoTocConfig::entriesPerPage() のチャンクに分割します。各チャンクは 1 つのコンテンツストリーム文字列になります。エントリごとに、インデントは leftMargin + level * indentPerLevel です。フォントサイズはレベルごとに 0.5 pt 減少し、6.0 pt を下限とします。レベル 0 は太字のフォントキーを、より深いレベルは通常のキーを使用します。ページ番号が有効かつ存在する場合、任意のドットリーダーが間隙を埋め、番号は右揃えになります。タイトルとすべてのエントリ文字列は、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 モードの挙動

このモジュールでは暗号操作が一切発生しないため、FIPS モード固有の挙動はありません。ここではランダム性、ハッシュ、署名を消費するものはありません。

適合性

主張	標準	条項
TOC タイトルとエントリテキストを `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() から始めて、wither をチェーンします。オブジェクトは readonly なので、各 wither は新しいインスタンスを返します。
実際のページ番号は、独自のレイアウトパスから assignPageNumbers() で割り当てます。assignSequentialPages() はプレースホルダーのみを生成します。
entriesPerPage()、lineSpacing()、contentWidth() は設定の純粋な派生値です。レンダリング前にレイアウトを事前サイジングするために呼び出します。
getHeadings()、count()、reset() は、スキャン間でコレクターの蓄積状態を読み取り・クリアします。

公開の境界

このページは、外部から観測可能な挙動とサポートされる公開 API サーフェスのみを記載します。内部の名前空間パス、ヘルパークラス、メカニズムのテーブル、ランブックのファイル名、チケットのプレフィックスは対象外です。