Flow Layout

Auf einen Blick

NextPDF Pro platziert eine Folge von Flow-Elementen — Text, Bilder, Tabellen, Abstandshalter — auf Seiten und weist jedem eine konkrete Seite und Position zu. Das Seitenumbruch-Verhalten ist wählbar: gierig, Schusterjungen-vermeidend oder zusammenhaltend.

Verfügbarkeit & Lizenzierung

Diese Fähigkeit ist in NextPDF Pro (nextpdf/pro) enthalten und wird mit einem Lizenz-Envelope der Pro-Stufe aktiviert. Eine Bereitstellung ohne diese Berechtigung lädt die Klassen der Fähigkeit nicht. Es gibt kein separates funktionsbezogenes Lizenz-Flag; der Pro-Envelope aktiviert sie. Editionen vergleichen und Lizenz erwerben.

Installation

composer require nextpdf/pro:^3

Konzeptioneller Überblick

Die Streaming-Layout-Engine nimmt eine Liste von Flow-Elementen und eine Inhaltsregion entgegen, durchläuft dann die Elemente der Reihe nach und weist jedem eine Seite und Position zu. Wenn ein Element nicht in den verbleibenden vertikalen Raum passt, beginnt die Engine gemäß der konfigurierten Strategie eine neue Seite:

• StreamingLayoutEngine — die Engine. Wird mit einer LayoutRegion (dem Inhaltsbereich je Seite) und einer PageBreakStrategy konstruiert. Sie gibt ein LayoutResult der platzierten Elemente zurück.
• FlowElement / FlowElementType — das Elementmodell. Text und Tabellen können über Seiten hinweg umbrechen; die Engine platziert Bilder und Abstandshalter atomar.
• PageBreakStrategy — ein Enum mit drei Verhaltensweisen:
  • Greedy — umbrechen, sobald das nächste Element nicht passt.
  • AvoidOrphans — früh umbrechen, wenn nur wenig Raum verbleibt, um zu vermeiden, dass ein einzelnes Element oben auf einer neuen Seite stehen bleibt.
  • KeepTogether — das Mit-dem-Nächsten-zusammenhalten-Flag berücksichtigen, sodass paarweise Elemente nach Möglichkeit auf derselben Seite bleiben.

Flow Layout ist eine Element-Platzierungs-Engine. Sie berechnet Seiten- und Positionszuweisungen; sie ist keine HTML- oder CSS-Rendering-Engine. Für HTML-nach-PDF verwenden Sie die Core-HTML-Pipeline.

Warum es so funktioniert

Die Engine weist jedem Element in einem einzigen Vorwärtsdurchlauf eine Seite und Position zu. Sie puffert niemals einen vollständigen Dokumentbaum, um ihn später neu umzubrechen. Das hält den Speicherbedarf beschränkt, wie lange das Dokument auch läuft, und macht die Kosten linear zur Elementanzahl. Jede Seitenumbruch-Entscheidung ist ein lokales Prädikat über den aktuellen Cursor und die gewählte Strategie. So lösen sich gierig, Schusterjungen-Vermeidung und Zusammenhalten allesamt innerhalb desselben Streaming-Durchlaufs auf. Der Kompromiss ist die Vorwärtsfestlegung: ein übermäßig hohes Element läuft über, statt neu skaliert zu werden, und Zusammenhalten gilt nur, wenn beide paarweisen Elemente sich eine Seite teilen.

Design-Hintergrund: Dokumentgenerierung in großem Umfang.

API-Oberfläche

Class	Responsibility
StreamingLayoutEngine	Flow-Elementen Seiten und Positionen zuweisen.
FlowElement, FlowElementType	Elementmodell und Typ-Enum.
LayoutRegion	Inhaltsbereich je Seite.
PageBreakStrategy	Enum für Seitenumbruch-Verhalten.
LayoutResult, PlacedElement	Platzierungs-Ausgabe.

Codebeispiel — Schnellstart

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

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

Codebeispiel — Produktion

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

Randfälle & Fallstricke

• Die Engine platziert ein Element, das höher als die Region ist, dennoch, aber es kann überlaufen; dimensionieren Sie Elemente innerhalb der Regionshöhe.
• KeepTogether hält Paare nur dann zusammen, wenn beide auf eine Seite passen.
• AvoidOrphans reserviert vor dem Umbruch mindestens zwei Elementhöhen.

Performance

Das Layout ist linear in der Anzahl der Elemente. Die Engine ist streamend: Sie hält keinen vollständigen Dokumentbaum vor.

Sicherheitshinweise

Flow Layout arbeitet mit den Elementmetadaten, die Sie bereitstellen. Es führt kein I/O durch.

Konformität

Flow Layout implementiert das NextPDF-Platzierungsverhalten; es zielt auf keinen externen Layout-Standard.

Verhaltensvertrag

• StreamingLayoutEngine wird mit einer LayoutRegion und einer PageBreakStrategy konstruiert und gibt ein LayoutResult platzierter Elemente mit konkreten Seiten- und Positionszuweisungen zurück.
• PageBreakStrategy hat drei Verhaltensweisen: Greedy (umbrechen, wenn das nächste Element nicht passt), AvoidOrphans (früh umbrechen, mindestens zwei Elementhöhen reservieren) und KeepTogether (das Mit-dem-Nächsten-zusammenhalten berücksichtigen, sodass paarweise Elemente auf einer Seite bleiben, wenn beide passen).
• Text und Tabellen können über Seiten hinweg umbrechen; Bilder und Abstandshalter werden atomar platziert. Ein Element, das höher als die Region ist, wird dennoch platziert, kann aber überlaufen.
• Die Engine ist streamend: Sie hält keinen vollständigen Dokumentbaum vor und führt kein I/O durch.
• Dies ist eine Element-Platzierungs-Engine. Sie berechnet Seiten- und Positionszuweisungen; sie ist keine HTML- oder CSS-Rendering-Engine.

Hinweis zur Enterprise-Abgrenzung

Enterprise ändert das Flow-Layout-Verhalten nicht. Enterprise ergänzt Funktionen höherer Stufe, die separat dokumentiert sind; sie sind zur Nutzung der Platzierungs-Engine nicht erforderlich.

Core-Rückfalloption / Alternative

Es gibt keine Core-Element-Platzierungs-Engine mit Seitenumbruch-Strategien. Für HTML-nach-PDF-Rendering verwenden Sie die Open-Source-Core-HTML-Pipeline. Siehe /modules/html/.

Veröffentlichungsgrenze

Diese Seite dokumentiert ausschließlich extern beobachtbares Verhalten und die unterstützte öffentliche API-Oberfläche. Interne Namespace-Pfade, Helferklassen, Mechanismus-Tabellen, Runbook-Dateinamen und Ticket-Präfixe sind nicht Bestandteil des Umfangs.

Siehe auch

• Flow Layout — Deep Reference — vollständige Klassen- und Methodenreferenz.
• Document — Dokumentzusammenstellung.
• Core HTML module — HTML-nach-PDF-Rendering.