Flow Layout

Кратко

NextPDF Pro размещает последовательность flow-элементов — текст, изображения, таблицы, разделители — на страницах, присваивая каждому конкретную страницу и позицию. Поведение при разрыве страниц можно выбирать: жадное, с избеганием висячих строк или с удержанием вместе.

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

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

Установка

composer require nextpdf/pro:^3

Концептуальный обзор

Потоковый движок макета принимает список flow-элементов и область содержимого, затем обходит элементы по порядку и присваивает каждому страницу и позицию. Когда элемент не помещается в оставшееся вертикальное пространство, движок начинает новую страницу согласно настроенной стратегии:

• StreamingLayoutEngine — движок. Конструируется с LayoutRegion (область содержимого на странице) и PageBreakStrategy. Он возвращает LayoutResult из размещённых элементов.
• FlowElement / FlowElementType — модель элемента. Текст и таблицы могут разрываться между страницами; изображения и разделители движок размещает атомарно.
• PageBreakStrategy — перечисление с тремя видами поведения:
  • Greedy — разрывать, как только следующий элемент не помещается.
  • AvoidOrphans — разрывать заранее, когда остаётся лишь небольшое пространство, чтобы не оставлять единственный элемент в начале новой страницы.
  • KeepTogether — учитывать флаг удержания со следующим, чтобы парные элементы оставались на одной странице, когда это возможно.

Flow Layout — это движок размещения элементов. Он вычисляет назначения страниц и позиций; это не движок отрисовки HTML или CSS. Для отрисовки HTML в PDF используйте конвейер HTML из Core.

Почему это работает именно так

Движок присваивает каждому элементу страницу и позицию за один проход вперёд. Он никогда не буферизует полное дерево документа, чтобы переверстать его позже. Это удерживает потребление памяти ограниченным, каким бы длинным ни был документ, и делает стоимость линейной по числу элементов. Каждое решение о разрыве страницы — это локальный предикат по текущему курсору и выбранной стратегии. Поэтому жадная стратегия, избегание висячих строк и удержание вместе разрешаются в рамках одного и того же потокового обхода. Компромисс — фиксация вперёд: слишком высокий элемент выходит за границы, а не масштабируется, а удержание вместе действует, только когда оба парных элемента находятся на одной странице.

Проектный контекст: Массовая генерация документов.

Поверхность API

Класс	Назначение
StreamingLayoutEngine	Назначать страницы и позиции flow-элементам.
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 работает с метаданными элементов, которые вы предоставляете. Он не выполняет ввод-вывод.

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

Flow Layout реализует поведение размещения NextPDF; он не ориентируется на внешний стандарт макета.

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

• StreamingLayoutEngine конструируется с LayoutRegion и PageBreakStrategy и возвращает LayoutResult из размещённых элементов с конкретными назначениями страниц и позиций.
• PageBreakStrategy имеет три вида поведения: Greedy (разрыв, когда следующий элемент не помещается), AvoidOrphans (разрыв заранее с резервом не менее двух высот элемента) и KeepTogether (учёт удержания со следующим, чтобы парные элементы оставались на одной странице, когда обе помещаются).
• Текст и таблицы могут разрываться между страницами; изображения и разделители размещаются атомарно. Элемент выше области всё равно размещается, но может выйти за границы.
• Движок потоковый: он не хранит полное дерево документа и не выполняет ввод-вывод.
• Это движок размещения элементов. Он вычисляет назначения страниц и позиций; это не движок отрисовки HTML или CSS.

Примечание о границе Enterprise

Enterprise не меняет поведение Flow Layout. Enterprise добавляет возможности более высокого уровня, документированные отдельно; они не требуются для использования движка размещения.

Резервный вариант Core / альтернатива

В Core нет движка размещения элементов со стратегиями разрыва страниц. Для отрисовки HTML в PDF используйте конвейер HTML из Core с открытым исходным кодом. См. /modules/html/.

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

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

См. также

• Flow Layout — Deep Reference — полный справочник классов и методов.
• Document — сборка документов.
• Core HTML module — отрисовка HTML в PDF.