跳到內容
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 個型別化參數（title、depth、fonts、spacing、margins、colors、page size）不可變的組態載體——唯讀；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不可變的標題值物件——唯讀；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() 會以一個有界的樣式（不分大小寫、dot 比對換行）比對 <h1>–<h6>，要求同一層級的開/閉標籤成對平衡。每一個相符項目的內層內容會被去除標籤、解碼實體 （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 使用粗體字型鍵，較深層則使用一般字型鍵。當頁碼啟用且存在時，選用的點狀導引線會填滿間隙，且數字靠右對齊。標題與每一個項目字串都會依 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 模式行為」的區段

本模組不發生任何密碼學運算，因此沒有任何 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。此物件為唯讀，因此每個 wither 都會回傳一個新實例。
  • 以你自己的排版過程搭配 assignPageNumbers() 指派真實頁碼； assignSequentialPages() 僅產生佔位值。
  • entriesPerPage()、lineSpacing() 與 contentWidth() 是組態的純衍生值；在彩現前呼叫它們以預先量測版面尺寸。
  • getHeadings()、count() 與 reset() 會在多次掃描之間讀取並清除收集器累積的狀態。

發佈邊界

標題為「發佈邊界」的區段

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

另請參閱

標題為「另請參閱」的區段