Flow Layout — Referencia detallada

De un vistazo

Esta página es la referencia detallada del módulo Pro Flow Layout. Cubre el motor de colocación, el modelo de elementos, las estrategias de salto de página, sus contratos de comportamiento y sus modos de fallo. StreamingLayoutEngine recorre en orden una lista de valores FlowElement. A cada uno le asigna un índice de página de base cero y una posición dentro de un LayoutRegion. El resultado es un LayoutResult de registros inmutables PlacedElement. El módulo solo calcula la colocación; no renderiza nada ni realiza operaciones de E/S.

Disponibilidad y licencia

Esta capacidad se incluye en NextPDF Pro (nextpdf/pro) y se activa con un sobre de licencia de nivel Pro. Un despliegue sin esa habilitación no carga las clases de la capacidad. Comparar ediciones y obtener una licencia.

No existe ningún indicador de licencia por función. Es una capacidad de la edición Pro.

Superficie pública de la API

Todos los símbolos residen en el espacio de nombres NextPDF\Pro\FlowLayout. Todos los objetos de valor son final e inmutables.

Símbolo	Parámetros	Comportamiento por defecto	Devuelve	Lanza o falla con	Notas
StreamingLayoutEngine::__construct	LayoutRegion $region, PageBreakStrategy $strategy = PageBreakStrategy::Greedy	Vincula un área de contenido por página a una estrategia de salto	StreamingLayoutEngine	—	La estrategia es Greedy por defecto.
StreamingLayoutEngine::layout	list<FlowElement> $elements	Una única pasada hacia adelante; colocación secuencial con saltos de página dirigidos por la estrategia	LayoutResult	Nunca lanza	Una lista vacía produce una página vacía.
StreamingLayoutEngine::withStrategy	PageBreakStrategy $strategy	Deriva un nuevo motor con la misma región	self	—	El receptor no se modifica.
StreamingLayoutEngine::withRegion	LayoutRegion $region	Deriva un nuevo motor con la misma estrategia	self	—	El receptor no se modifica.
FlowElement::__construct	FlowElementType $type, string $content, float $widthPt = 0, float $heightPt = 0, float $marginTopPt = 0, float $marginBottomPt = 0, bool $keepWithNext = false	Objeto de valor de elemento inmutable	FlowElement	—	Única vía de construcción para elementos Table.
FlowElement::text	string $content, float $height	Elemento de texto con una altura medida por el llamador	self (estático)	—	Un ancho 0 se resuelve al ancho de la región en el momento de la colocación.
FlowElement::image	string $path, float $width, float $height	Elemento de imagen; content transporta la ruta	self (estático)	—	El motor nunca abre el archivo.
FlowElement::spacer	float $height	Espacio en blanco vertical con contenido vacío	self (estático)	—	—
FlowElement::pageBreak	—	Marcador de salto explícito	self (estático)	—	No emite ningún PlacedElement.
FlowElement::totalHeight	—	Altura más los márgenes superior e inferior	float	—	Todas las comprobaciones de ajuste usan este valor.
FlowElementType	casos de enum Text, Image, Table, Spacer, PageBreak	Respaldado por cadena: text, image, table, spacer, page_break	—	—	—
FlowElementType::isBreakable	—	Text y Table devuelven true; los demás devuelven false	bool	—	Solo clasificación; véase el contrato de colocación atómica más abajo.
LayoutRegion::__construct	float $x, float $y, float $width, float $height	Caja de contenido con origen en la esquina superior izquierda, medida en puntos	LayoutRegion	—	Sin validación; los valores se toman tal cual.
LayoutRegion::contains	float $px, float $py	Prueba de punto en región inclusiva con el límite	bool	—	—
LayoutRegion::remainingHeight	float $currentY	Altura de la región menos el desplazamiento vertical consumido	float	—	Cero o negativo una vez que el cursor ha desbordado.
LayoutResult::__construct	list<PlacedElement> $placements, int $pageCount, float $totalHeightPt	Resultado inmutable de la maquetación	LayoutResult	—	—
LayoutResult::placementsOnPage	int $pageIndex	Filtra las colocaciones por índice de página de base cero	list<PlacedElement>	—	La lista devuelta se reindexa.
LayoutResult::isEmpty	—	True cuando no se colocó ningún elemento	bool	—	True para entradas vacías y de solo saltos.
PageBreakStrategy	casos de enum Greedy, AvoidOrphans, KeepTogether	Respaldado por cadena: greedy, avoid_orphans, keep_together	—	—	—
PageBreakStrategy::label	—	Etiqueta legible de la estrategia	string	—	—
PlacedElement::__construct	FlowElement $element, int $pageIndex, float $x, float $y, float $width, float $height	Registro de colocación inmutable	PlacedElement	—	Las coordenadas están en puntos, con origen en la esquina superior izquierda.

public function layout(array $elements): LayoutResult
public function withStrategy(PageBreakStrategy $strategy): self
public function withRegion(LayoutRegion $region): self

public static function text(string $content, float $height): self
public static function image(string $path, float $width, float $height): self
public static function spacer(float $height): self
public static function pageBreak(): self

Contrato de comportamiento

StreamingLayoutEngine::layout() realiza una única pasada hacia adelante sobre la lista de entrada. Para cada elemento comprueba el ajuste, salta de página cuando es necesario y luego registra un PlacedElement. Una lista de entrada vacía devuelve un LayoutResult sin colocaciones, con un recuento de páginas de 1 y una altura total de 0.

La geometría de colocación es determinista:

• x es el borde izquierdo de la región.
• y es la posición actual del cursor más el margen superior del elemento.
• width es el widthPt del elemento cuando es positivo; de lo contrario, el ancho de la región.
• height es el heightPt del elemento, exactamente como se suministra.

Tras cada colocación el cursor avanza en totalHeight(), incluidos los márgenes. La misma cantidad se acumula en LayoutResult::totalHeightPt.

Reglas de salto de página, en orden de evaluación:

• Un elemento PageBreak explícito incrementa el índice de página y restablece el cursor a la parte superior de la región. No emite ninguna colocación ni añade nada a la altura total.
• Cuando el totalHeight() de un elemento supera la altura restante, el motor salta — salvo que el cursor ya esté en la parte superior de la página.
• Greedy no añade ninguna condición adicional: los elementos que caben siempre se colocan.
• AvoidOrphans salta antes de un elemento que cabe cuando el espacio que quedaría tras la colocación sería positivo pero inferior a la mitad de la altura requerida por el propio elemento. La altura del propio elemento es la unidad de referencia, con un divisor fijo de dos; no interviene ninguna métrica de fuente. Nunca salta en la parte superior de una página.
• KeepTogether salta antes de un elemento que cabe cuando su indicador keepWithNext está activado, existe un elemento siguiente, el cursor no está en la parte superior de la página y el totalHeight() combinado de ambos elementos supera el espacio restante. El indicador en el último elemento no tiene efecto.

Colocación atómica: el motor coloca cada elemento como una unidad. Nunca divide el contenido de un elemento entre páginas. FlowElementType::isBreakable() clasifica qué tipos puede pre-dividir un llamador en elementos más pequeños; el propio motor no lo consulta.

Ausencia de estado y determinismo: el motor solo mantiene su región y su estrategia. layout() no comparte estado entre llamadas, y entradas idénticas producen resultados idénticos. withStrategy() y withRegion() devuelven nuevos motores y nunca modifican el receptor.

Casos límite y modos de fallo

• Ningún método de este módulo lanza. No hay ninguna jerarquía de excepciones que capturar.
• Los constructores no validan nada. Las dimensiones de región negativas o cero, las alturas de elemento negativas y los márgenes negativos se aceptan y fluyen por la aritmética sin cambios.
• Un elemento más alto que la región se coloca igualmente. En la parte superior de una página se coloca allí y desborda; en otro lugar el motor salta primero y desborda una página nueva. El siguiente elemento activa entonces siempre un salto, de modo que el desbordamiento queda confinado a una sola página.
• Un PageBreak inicial coloca el primer elemento de contenido en el índice de página 1, dando un recuento de páginas de al menos 2.
• Elementos PageBreak consecutivos avanzan cada uno el contador de páginas, produciendo páginas en blanco. Uno final deja una última página vacía en pageCount.
• El mantener juntos solo se cumple cuando ambos elementos emparejados caben juntos en una página. Un par cuya altura combinada supera una página completa se divide igualmente.
• Un widthPt no positivo se resuelve al ancho de la región; la comprobación de sustitución es estrictamente mayor que cero.
• remainingHeight() puede devolver cero o un valor negativo una vez que el cursor ha desbordado. contains() trata el límite de la región como interior.
• placementsOnPage() con un índice fuera de rango devuelve una lista vacía.
• Este módulo no realiza operaciones criptográficas y no define ningún comportamiento específico de FIPS.

Conformidad

Flow Layout implementa un comportamiento de colocación definido por NextPDF. No apunta a ningún estándar externo de maquetación o tipografía, por lo que esta página no incluye ninguna tabla de citas normativas. Las estrategias de salto de página son semántica de NextPDF; no son implementaciones de las propiedades de fragmentación de CSS ni de ningún modelo keep de XSL-FO. Todas las dimensiones se expresan en puntos, coincidiendo con las unidades que consume el escritor de Core.

Estas afirmaciones describen únicamente capacidad. NextPDF no posee ninguna certificación de conformidad, y no se realiza ni se implica ninguna reclamación de certificación.

Notas de desarrollo

• Medir el contenido aguas arriba. El motor consume las alturas suministradas por el llamador; no tiene métricas de fuente y no realiza ninguna medición de texto.
• Pre-dividir el texto o el contenido de tabla largos en múltiples elementos antes de la maquetación. Usar isBreakable() para decidir qué tipos puede dividir un fragmentador.
• Reutilizar un único motor por geometría de página. Derivar variantes de forma económica con withStrategy() y withRegion().
• Agrupar la salida por página con placementsOnPage() al renderizar página a página.
• La maquetación es una única pasada, lineal en el número de elementos, y no retiene ningún árbol de documento. Los resultados son deterministas, lo que se presta a pruebas de archivo de referencia.
• Para el renderizado de HTML a PDF, usar en su lugar la canalización HTML de Core; este módulo no es un motor de HTML ni de CSS.

Límite de publicación

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

Véase también

• Flow Layout — descripción general de la capacidad
• Document — Referencia detallada
• Módulo HTML de Core