Flow Layout

速覽

NextPDF Pro 會將一連串流式元素 —— 文字、影像、表格、間隔元素 —— 放置到頁面上，並為每一個指派具體的頁面與位置。分頁行為可選擇：greedy、orphan-avoiding 或 keep-together。

可用性與授權

此能力隨 NextPDF Pro（nextpdf/pro）提供，並在 Pro 等級的授權封套下啟用。未具備該授權的部署不會載入此能力的類別。並沒有獨立的逐功能授權旗標；由 Pro 封套啟用它。比較各版本並取得授權。

安裝

composer require nextpdf/pro:^3

概念總覽

串流式排版引擎會接受一份流式元素清單與一個內容區域，接著依序走訪這些元素，並為每一個指派一個頁面與位置。當某個元素無法容納於剩餘的垂直空間時，引擎會依設定的策略開啟新的一頁：

• StreamingLayoutEngine —— 引擎本身。以一個 LayoutRegion（每頁的內容區域）與一個 PageBreakStrategy 建構。它會回傳一個由已放置元素組成的 LayoutResult。
• FlowElement / FlowElementType —— 元素模型。文字與表格可橫跨頁面斷開；引擎會以不可分割的方式放置影像與間隔元素。
• PageBreakStrategy —— 一個帶有三種行為的列舉：
  • Greedy —— 一旦下一個元素無法容納便立即斷頁。
  • AvoidOrphans —— 當只剩下少量空間時提早斷頁，以避免在新頁面頂端留下孤零零的單一元素。
  • KeepTogether —— 遵循 keep-with-next 旗標，讓成對元素在可能時留在同一頁。

Flow Layout 是一個元素放置引擎。它計算頁面與位置的指派；它不是 HTML 或 CSS 繪製引擎。若需要 HTML 轉 PDF，請使用 Core HTML 管線。

為何如此設計

引擎在單一次前向走訪中為每個元素指派頁面與位置。它絕不會為了稍後重新排版而緩衝整棵文件樹。這讓無論文件跑得多長，記憶體都維持有界，並使成本與元素數量呈線性關係。每個斷頁決策都是針對目前游標與所選策略的區域性判定式。因此 greedy、orphan-avoidance 與 keep-together 全都在同一次串流走訪內解決。其取捨在於前向承諾：過高的元素會溢出而非重新縮放，而 keep-together 只有在成對的兩個元素共享同一頁時才成立。

設計背景：大量文件生成。

API 介面

類別	職責
StreamingLayoutEngine	為流式元素指派頁面與位置。
FlowElement, FlowElementType	元素模型與型別列舉。
LayoutRegion	每頁的內容區域。
PageBreakStrategy	分頁行為列舉。
LayoutResult, PlacedElement	放置輸出。

程式碼範例 —— 快速上手

use NextPDF\Pro\FlowLayout\{StreamingLayoutEngine, LayoutRegion, PageBreakStrategy};

$engine = new StreamingLayoutEngine(
    region:   new LayoutRegion(/* x, y, width, height */),
    strategy: PageBreakStrategy::AvoidOrphans,
);
$result = $engine->layout($elements);

程式碼範例 —— 正式環境

$result = $engine->layout($elements);
foreach ($result->placements as $placed) {
    $logger->debug('flow.placed', [
        'page' => $placed->pageIndex,
        'type' => $placed->element->type->value,
    ]);
}

邊界案例與陷阱

• 對於高度超過區域的元素，引擎仍會放置它，但它可能溢出；請將元素大小控制在區域高度之內。
• KeepTogether 只有在兩者都能容納於同一頁時，才會將成對元素保持在一起。
• AvoidOrphans 在斷頁前至少保留兩個元素高度的空間。

效能

排版與元素數量呈線性關係。引擎為串流式：它不保留完整的文件樹。

安全注意事項

Flow Layout 在你所提供的元素中繼資料上運作。它不執行任何 I/O。

一致性

Flow Layout 實作的是 NextPDF 放置行為；它不以任何外部排版標準為目標。

行為合約

• StreamingLayoutEngine 以一個 LayoutRegion 與一個 PageBreakStrategy 建構，並回傳一個由已放置元素組成、帶有具體頁面與位置指派的 LayoutResult。
• PageBreakStrategy 有三種行為：Greedy（下一個元素無法容納時斷頁）、AvoidOrphans（提早斷頁，至少保留兩個元素高度），以及 KeepTogether（遵循 keep-with-next，讓成對元素在兩者都能容納時留在同一頁）。
• 文字與表格可橫跨頁面斷開；影像與間隔元素以不可分割的方式放置。高度超過區域的元素仍會被放置，但可能溢出。
• 引擎為串流式：它不保留完整的文件樹，也不執行任何 I/O。
• 這是一個元素放置引擎。它計算頁面與位置的指派；它不是 HTML 或 CSS 繪製引擎。

Enterprise 邊界註記

Enterprise 不會改變 Flow Layout 的行為。Enterprise 新增更高等級的功能，另行記載；它們對於使用放置引擎並非必要。

Core 回退/替代方案

沒有任何帶分頁策略的 Core 元素放置引擎。若需要 HTML 轉 PDF 繪製，請使用開源 Core HTML 管線。請參閱 /modules/html/。

出版邊界

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

另請參閱

• Flow Layout —— 深入參考 —— 完整的類別與方法參考。
• Document —— 文件組裝。
• Core HTML 模組 —— HTML 轉 PDF 繪製。