流式布局

速览

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 —— 遵循”与下一个保持在一起”标志，使成对元素尽可能停留在同一页。

Flow Layout 是一个元素放置引擎。它计算页面和位置分配；它不是 HTML 或 CSS 渲染引擎。对于 HTML 到 PDF，请使用 Core HTML 管线。

它为何如此工作

引擎在一次向前的遍历中为每个元素分配页面和位置。它从不缓冲完整的文档树以便稍后重排。这使得无论文档运行多长，内存都保持有界，并使成本随元素数量呈线性。每个断页决策都是对当前光标和所选策略的局部判定。因此贪婪、避免孤行和保持在一起都在同一次流式遍历中得到解决。代价是向前的承诺：过高的元素会溢出而非重新缩放，且保持在一起仅在成对的两个元素共享同一页时才成立。

设计背景：大批量文档生成。

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（遵循”与下一个保持在一起”，使成对元素在两者都放得下时停留在同一页）。
• 文本和表格可以跨页断开；图像和间隔作为原子整体放置。高于区域的元素仍会被放置，但可能溢出。
• 引擎是流式的：它不保留完整的文档树，也不执行任何 I/O。
• 这是一个元素放置引擎。它计算页面和位置分配；它不是 HTML 或 CSS 渲染引擎。

Enterprise 边界说明

Enterprise 不改变 Flow Layout 的行为。Enterprise 增加了更高层级的功能，单独编写文档；它们对于使用该放置引擎并非必需。

Core 回退/替代方案

没有带分页策略的 Core 元素放置引擎。对于 HTML 到 PDF 渲染，请使用开源 Core HTML 管线。参见 /modules/html/。

发布边界

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

另请参阅

• Flow Layout —— 深度参考 —— 完整的类与方法参考。
• Document —— 文档组装。
• Core HTML module —— HTML 到 PDF 渲染。