Pro editie

Flow Layout — Diepe referentie

In één oogopslag

Deze pagina is de diepe referentie voor de Pro Flow Layout-module. Ze behandelt de plaatsings-engine, het elementmodel, de pagina-einde-strategieën, hun gedragscontracten en hun faalmodi. StreamingLayoutEngine doorloopt een lijst van FlowElement-waarden op volgorde. De engine wijst elke waarde een nul-gebaseerde pagina-index toe en een positie binnen een LayoutRegion. Het resultaat is een LayoutResult van immutable PlacedElement-records. De module berekent alleen de plaatsing; ze rendert niets en voert geen I/O uit.

Beschikbaarheid en licentie

Deze functionaliteit wordt geleverd in NextPDF Pro (nextpdf/pro) en wordt geactiveerd met een licentie-envelope van het Pro-niveau. Een deployment zonder die entitlement laadt de klassen van de functionaliteit niet. Vergelijk edities en vraag een licentie aan.

Er bestaat geen licentieflag per functie. Dit is een functionaliteit van de Pro-editie.

Publiek API-oppervlak

Alle symbolen bevinden zich in de namespace NextPDF\Pro\FlowLayout. Alle value objects zijn final en immutable.

Symbool	Parameters	Standaardgedrag	Retourneert	Gooit of faalt met	Opmerkingen
`StreamingLayoutEngine::__construct`	`LayoutRegion $region`, `PageBreakStrategy $strategy = PageBreakStrategy::Greedy`	Koppelt een contentgebied per pagina aan een break-strategie	`StreamingLayoutEngine`	—	Strategie is standaard `Greedy`.
`StreamingLayoutEngine::layout`	`list<FlowElement> $elements`	Eén voorwaartse pass; sequentiële plaatsing met strategiegestuurde pagina-einden	`LayoutResult`	Gooit nooit	Een lege lijst levert één lege pagina op.
`StreamingLayoutEngine::withStrategy`	`PageBreakStrategy $strategy`	Leidt een nieuwe engine af met dezelfde regio	`self`	—	De ontvanger blijft ongewijzigd.
`StreamingLayoutEngine::withRegion`	`LayoutRegion $region`	Leidt een nieuwe engine af met dezelfde strategie	`self`	—	De ontvanger blijft ongewijzigd.
`FlowElement::__construct`	`FlowElementType $type`, `string $content`, `float $widthPt = 0`, `float $heightPt = 0`, `float $marginTopPt = 0`, `float $marginBottomPt = 0`, `bool $keepWithNext = false`	Immutable value object voor elementen	`FlowElement`	—	Enige constructiepad voor `Table`-elementen.
`FlowElement::text`	`string $content`, `float $height`	Tekstelement met een door de aanroeper gemeten hoogte	`self` (static)	—	Breedte 0 wordt bij plaatsing de regiobreedte.
`FlowElement::image`	`string $path`, `float $width`, `float $height`	Afbeeldingselement; `content` bevat het pad	`self` (static)	—	De engine opent het bestand nooit.
`FlowElement::spacer`	`float $height`	Verticale witruimte met lege content	`self` (static)	—	—
`FlowElement::pageBreak`	—	Expliciete break-marker	`self` (static)	—	Zendt geen `PlacedElement` uit.
`FlowElement::totalHeight`	—	Hoogte plus boven- en ondermarge	`float`	—	Alle pascontroles gebruiken deze waarde.
`FlowElementType`	enum-cases `Text`, `Image`, `Table`, `Spacer`, `PageBreak`	String-backed: `text`, `image`, `table`, `spacer`, `page_break`	—	—	—
`FlowElementType::isBreakable`	—	`Text` en `Table` retourneren true; overige retourneren false	`bool`	—	Alleen classificatie; zie het atomaire-plaatsingscontract hieronder.
`LayoutRegion::__construct`	`float $x`, `float $y`, `float $width`, `float $height`	Contentbox met oorsprong linksboven, gemeten in punten	`LayoutRegion`	—	Geen validatie; waarden worden overgenomen zoals gegeven.
`LayoutRegion::contains`	`float $px`, `float $py`	Punt-in-regio-test inclusief de grens	`bool`	—	—
`LayoutRegion::remainingHeight`	`float $currentY`	Regiohoogte minus de verbruikte verticale offset	`float`	—	Nul of negatief zodra de cursor is overgelopen.
`LayoutResult::__construct`	`list<PlacedElement> $placements`, `int $pageCount`, `float $totalHeightPt`	Immutable lay-outuitkomst	`LayoutResult`	—	—
`LayoutResult::placementsOnPage`	`int $pageIndex`	Filtert plaatsingen op nul-gebaseerde pagina-index	`list<PlacedElement>`	—	De geretourneerde lijst wordt opnieuw geïndexeerd.
`LayoutResult::isEmpty`	—	True wanneer er geen elementen zijn geplaatst	`bool`	—	True voor lege en alleen-break-invoer.
`PageBreakStrategy`	enum-cases `Greedy`, `AvoidOrphans`, `KeepTogether`	String-backed: `greedy`, `avoid_orphans`, `keep_together`	—	—	—
`PageBreakStrategy::label`	—	Voor mensen leesbaar strategielabel	`string`	—	—
`PlacedElement::__construct`	`FlowElement $element`, `int $pageIndex`, `float $x`, `float $y`, `float $width`, `float $height`	Immutable plaatsingsrecord	`PlacedElement`	—	Coördinaten zijn in punten, oorsprong linksboven.

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

Gedragscontract

StreamingLayoutEngine::layout() voert één voorwaartse pass over de invoerlijst uit. Voor elk element controleert ze de pasvorm, breekt ze de pagina wanneer nodig en legt ze vervolgens een PlacedElement vast. Een lege invoerlijst retourneert een LayoutResult zonder plaatsingen, met een paginateller van 1 en een totale hoogte van 0.

De plaatsingsgeometrie is deterministisch:

x is de linkerrand van de regio.
y is de huidige cursorpositie plus de bovenmarge van het element.
width is de widthPt van het element indien positief, anders de regiobreedte.
height is de heightPt van het element, exact zoals aangeleverd.

Na elke plaatsing schuift de cursor op met totalHeight(), marges inbegrepen. Hetzelfde bedrag wordt opgeteld bij LayoutResult::totalHeightPt.

Pagina-einde-regels, in evaluatievolgorde:

Een expliciet PageBreak-element verhoogt de pagina-index en zet de cursor terug naar de bovenkant van de regio. Het zendt geen plaatsing uit en voegt niets toe aan de totale hoogte.
Wanneer de totalHeight() van een element de resterende hoogte overschrijdt, breekt de engine — tenzij de cursor al bovenaan de pagina staat.
Greedy voegt geen verdere voorwaarde toe: passende elementen worden altijd geplaatst.
AvoidOrphans breekt vóór een passend element wanneer de ruimte die na plaatsing overblijft positief zou zijn maar onder de helft van de vereiste hoogte van het element zelf. De eigen hoogte van het element is de referentie-eenheid, met een vaste deler van twee; er is geen font-metric bij betrokken. Het breekt nooit bovenaan een pagina.
KeepTogether breekt vóór een passend element wanneer de keepWithNext-flag is gezet, er een volgend element bestaat, de cursor niet bovenaan de pagina staat en de gecombineerde totalHeight() van beide elementen de resterende ruimte overschrijdt. De flag op het laatste element heeft geen effect.

Atomaire plaatsing: de engine plaatst elk element als één geheel. Ze splitst elementinhoud nooit over pagina’s. FlowElementType::isBreakable() classificeert welke types een aanroeper vooraf in kleinere elementen mag opsplitsen; de engine zelf raadpleegt het niet.

Statusloosheid en determinisme: de engine houdt alleen zijn regio en strategie vast. layout() deelt geen status tussen aanroepen, en identieke invoer levert identieke resultaten op. withStrategy() en withRegion() retourneren nieuwe engines en muteren de ontvanger nooit.

Randgevallen en faalmodi

Geen enkele methode in deze module gooit. Er is geen exception-hiërarchie om te vangen.
Constructors valideren niets. Negatieve of nul-regioafmetingen, negatieve elementhoogtes en negatieve marges worden geaccepteerd en stromen ongewijzigd door de berekening.
Een element dat hoger is dan de regio wordt toch geplaatst. Bovenaan een pagina wordt het daar geplaatst en loopt het over; elders breekt de engine eerst en loopt het over een nieuwe pagina. Het volgende element veroorzaakt dan altijd een break, zodat het overlopen tot één pagina beperkt blijft.
Een voorafgaand PageBreak plaatst het eerste contentelement op pagina-index 1, wat een paginateller van minstens 2 oplevert.
Opeenvolgende PageBreak-elementen verhogen elk de paginateller en produceren blanco pagina’s. Een afsluitende laat een laatste lege pagina in pageCount achter.
Keep-together geldt alleen wanneer beide gepaarde elementen samen op één pagina passen. Een paar waarvan de gecombineerde hoogte een volledige pagina overschrijdt, wordt toch gesplitst.
Een niet-positieve widthPt wordt de regiobreedte; de substitutiecontrole is strikt groter dan nul.
remainingHeight() kan nul of een negatieve waarde retourneren zodra de cursor is overgelopen. contains() behandelt de regiogrens als binnen.
placementsOnPage() met een index buiten bereik retourneert een lege lijst.
Deze module voert geen cryptografische bewerkingen uit en definieert geen FIPS-specifiek gedrag.

Conformiteit

Flow Layout implementeert door NextPDF gedefinieerd plaatsingsgedrag. Het richt zich niet op een externe lay-out- of typografiestandaard, dus deze pagina bevat geen normatieve citaattabel. De pagina-einde-strategieën zijn NextPDF-semantiek; het zijn geen implementaties van CSS-fragmentatie-eigenschappen of van enig XSL-FO-keep-model. Alle afmetingen worden uitgedrukt in punten, overeenkomstig de eenheden die de Core-writer verwerkt.

Deze uitspraken beschrijven uitsluitend functionaliteit. NextPDF beschikt over geen conformiteitscertificering, en er wordt geen certificeringsclaim gemaakt of geïmpliceerd.

Ontwikkelnotities

Meet content stroomopwaarts. De engine verbruikt door de aanroeper aangeleverde hoogtes; ze heeft geen font-metrics en voert geen tekstmeting uit.
Splits lange tekst- of tabelinhoud vooraf in meerdere elementen vóór de lay-out. Gebruik isBreakable() om te bepalen welke types een chunker mag splitsen.
Hergebruik één engine per paginageometrie. Leid varianten goedkoop af met withStrategy() en withRegion().
Groepeer de uitvoer per pagina met placementsOnPage() bij het pagina-voor-pagina renderen.
De lay-out is één pass, lineair in het aantal elementen, en behoudt geen documentboom. Resultaten zijn deterministisch, wat geschikt is voor golden-file-tests.
Gebruik voor HTML-naar-PDF-rendering in plaats daarvan de Core HTML-pipeline; deze module is geen HTML- of CSS-engine.

Publicatiegrens

Deze pagina documenteert alleen extern waarneembaar gedrag en het ondersteunde publieke API-oppervlak. Interne namespace-paden, helperklassen, mechanismetabellen, runbook-bestandsnamen en ticket-prefixes vallen buiten de scope.