Maquetación de flujo

De un vistazo

NextPDF Pro coloca una secuencia de elementos en flujo —texto, imágenes, tablas, espaciadores— en las páginas, asignando a cada uno una página y una posición concretas. El comportamiento de salto de página es seleccionable: voraz, evitando huérfanos o manteniendo unido.

Disponibilidad y licencias

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin ese derecho de uso no carga las clases de la capacidad. No hay ningún indicador de licencia independiente por función; el sobre Pro la habilita. Compare ediciones y obtenga una licencia.

Instalación

composer require nextpdf/pro:^3

Descripción conceptual

El motor de maquetación en streaming toma una lista de elementos en flujo y una región de contenido, luego recorre los elementos en orden y asigna a cada uno una página y una posición. Cuando un elemento no cabe en el espacio vertical restante, el motor inicia una nueva página según la estrategia configurada:

• StreamingLayoutEngine — el motor. Se construye con una LayoutRegion (el área de contenido por página) y una PageBreakStrategy. Devuelve un LayoutResult de elementos colocados.
• FlowElement / FlowElementType — el modelo de elementos. El texto y las tablas pueden dividirse entre páginas; el motor coloca las imágenes y los espaciadores de forma atómica.
• PageBreakStrategy — un enum con tres comportamientos:
  • Greedy — saltar en cuanto el siguiente elemento no cabe.
  • AvoidOrphans — saltar antes cuando solo queda una pequeña cantidad de espacio, para evitar dejar un único elemento en la parte superior de una nueva página.
  • KeepTogether — respetar el indicador de mantener-con-el-siguiente para que los elementos emparejados permanezcan en la misma página cuando sea posible.

Flow Layout es un motor de colocación de elementos. Calcula las asignaciones de página y posición; no es un motor de renderizado de HTML ni de CSS. Para HTML a PDF, use el pipeline HTML de Core.

Por qué funciona así

El motor asigna a cada elemento una página y una posición en una única pasada hacia adelante. Nunca almacena en búfer un árbol de documento completo para reflujarlo después. Eso mantiene la memoria acotada por muy largo que sea el documento, y hace que el coste sea lineal respecto al número de elementos. Cada decisión de salto de página es un predicado local sobre el cursor actual y la estrategia elegida. Así, voraz, evitación de huérfanos y mantener-unido se resuelven todos dentro del mismo recorrido en streaming. La contrapartida es el compromiso hacia adelante: un elemento demasiado alto se desborda en lugar de reescalarse, y mantener-unido solo se cumple cuando ambos elementos emparejados comparten página.

Contexto de diseño: Generación de documentos de alto volumen.

Superficie de la API

Clase	Responsabilidad
StreamingLayoutEngine	Asignar páginas y posiciones a los elementos en flujo.
FlowElement, FlowElementType	Modelo de elementos y enum de tipo.
LayoutRegion	Área de contenido por página.
PageBreakStrategy	Enum de comportamiento de salto de página.
LayoutResult, PlacedElement	Salida de colocación.

Ejemplo de código — Inicio rápido

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

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

Ejemplo de código — Producción

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

Casos límite y trampas

• El motor sigue colocando un elemento más alto que la región, pero puede desbordarse; dimensione los elementos dentro de la altura de la región.
• KeepTogether mantiene los pares juntos solo cuando ambos caben en una página.
• AvoidOrphans reserva al menos dos alturas de elemento antes de saltar.

Rendimiento

La maquetación es lineal respecto al número de elementos. El motor es de streaming: no retiene un árbol de documento completo.

Notas de seguridad

Flow Layout opera sobre los metadatos de elemento que usted suministra. No realiza ninguna E/S.

Conformidad

Flow Layout implementa el comportamiento de colocación de NextPDF; no apunta a ningún estándar de maquetación externo.

Contrato de comportamiento

• StreamingLayoutEngine se construye con una LayoutRegion y una PageBreakStrategy y devuelve un LayoutResult de elementos colocados con asignaciones de página y posición concretas.
• PageBreakStrategy tiene tres comportamientos: Greedy (saltar cuando el siguiente elemento no cabe), AvoidOrphans (saltar antes, reservando al menos dos alturas de elemento) y KeepTogether (respetar mantener-con-el-siguiente para que los elementos emparejados permanezcan en una página cuando ambos caben).
• El texto y las tablas pueden dividirse entre páginas; las imágenes y los espaciadores se colocan de forma atómica. Un elemento más alto que la región sigue colocándose, pero puede desbordarse.
• El motor es de streaming: no retiene un árbol de documento completo y no realiza ninguna E/S.
• Es un motor de colocación de elementos. Calcula las asignaciones de página y posición; no es un motor de renderizado de HTML ni de CSS.

Nota sobre el límite de Enterprise

Enterprise no cambia el comportamiento de Flow Layout. Enterprise añade funciones de nivel superior documentadas por separado; no son necesarias para usar el motor de colocación.

Alternativa / respaldo de Core

No existe ningún motor de colocación de elementos en Core con estrategias de salto de página. Para el renderizado de HTML a PDF, use el pipeline HTML de Core de código abierto. Consulte /modules/html/.

Límite de publicación

Esta página documenta únicamente el comportamiento observable externamente y la superficie pública de la API admitida. Las rutas de espacio de nombres internas, las clases auxiliares, las tablas de mecanismos, los nombres de archivo de runbook y los prefijos de ticket quedan fuera del alcance.

Véase también

• Flow Layout — Referencia profunda — referencia completa de clases y métodos.
• Document — ensamblado de documentos.
• Módulo HTML de Core — renderizado de HTML a PDF.