Flow Layout — Référence détaillée

En bref

Cette page est la référence détaillée du module Flow Layout de Pro. Elle couvre le moteur de placement, le modèle d’éléments, les stratégies de saut de page, leurs contrats de comportement et leurs modes de défaillance. StreamingLayoutEngine parcourt dans l’ordre une liste de valeurs FlowElement. Il attribue à chacune un indice de page à base zéro et une position à l’intérieur d’une LayoutRegion. Le résultat est un LayoutResult composé d’enregistrements PlacedElement immuables. Le module calcule uniquement le placement ; il ne rend rien et n’effectue aucune E/S.

Disponibilité et licence

Cette fonctionnalité est fournie dans NextPDF Pro (nextpdf/pro) et s’active avec une enveloppe de licence de niveau Pro. Un déploiement dépourvu de ce droit ne charge pas les classes de la fonctionnalité. Compare les éditions et obtiens une licence.

Aucun indicateur de licence par fonctionnalité n’existe. Il s’agit d’une fonctionnalité de l’édition Pro.

Surface d’API publique

Tous les symboles résident dans l’espace de noms NextPDF\Pro\FlowLayout. Tous les objets valeur sont final et immuables.

Symbole	Paramètres	Comportement par défaut	Retourne	Lève ou échoue avec	Notes
StreamingLayoutEngine::__construct	LayoutRegion $region, PageBreakStrategy $strategy = PageBreakStrategy::Greedy	Lie une zone de contenu par page à une stratégie de saut	StreamingLayoutEngine	—	La stratégie est Greedy par défaut.
StreamingLayoutEngine::layout	list<FlowElement> $elements	Passe unique vers l’avant ; placement séquentiel avec sauts de page pilotés par la stratégie	LayoutResult	Ne lève jamais	Une liste vide produit une page vide.
StreamingLayoutEngine::withStrategy	PageBreakStrategy $strategy	Dérive un nouveau moteur avec la même région	self	—	Le récepteur est inchangé.
StreamingLayoutEngine::withRegion	LayoutRegion $region	Dérive un nouveau moteur avec la même stratégie	self	—	Le récepteur est inchangé.
FlowElement::__construct	FlowElementType $type, string $content, float $widthPt = 0, float $heightPt = 0, float $marginTopPt = 0, float $marginBottomPt = 0, bool $keepWithNext = false	Objet valeur d’élément immuable	FlowElement	—	Seul chemin de construction pour les éléments Table.
FlowElement::text	string $content, float $height	Élément texte avec une hauteur mesurée par l’appelant	self (static)	—	Une largeur de 0 se résout à la largeur de la région au moment du placement.
FlowElement::image	string $path, float $width, float $height	Élément image ; content porte le chemin	self (static)	—	Le moteur n’ouvre jamais le fichier.
FlowElement::spacer	float $height	Espace vertical avec contenu vide	self (static)	—	—
FlowElement::pageBreak	—	Marqueur de saut explicite	self (static)	—	N’émet aucun PlacedElement.
FlowElement::totalHeight	—	Hauteur plus les marges haute et basse	float	—	Toutes les vérifications d’ajustement utilisent cette valeur.
FlowElementType	cas d’énumération Text, Image, Table, Spacer, PageBreak	Adossé à des chaînes : text, image, table, spacer, page_break	—	—	—
FlowElementType::isBreakable	—	Text et Table retournent true ; les autres retournent false	bool	—	Classification seulement ; voir le contrat de placement atomique ci-dessous.
LayoutRegion::__construct	float $x, float $y, float $width, float $height	Boîte de contenu à origine en haut à gauche, mesurée en points	LayoutRegion	—	Aucune validation ; les valeurs sont prises telles quelles.
LayoutRegion::contains	float $px, float $py	Test d’appartenance d’un point à la région, bornes incluses	bool	—	—
LayoutRegion::remainingHeight	float $currentY	Hauteur de la région moins le décalage vertical consommé	float	—	Nulle ou négative une fois que le curseur a débordé.
LayoutResult::__construct	list<PlacedElement> $placements, int $pageCount, float $totalHeightPt	Résultat de mise en page immuable	LayoutResult	—	—
LayoutResult::placementsOnPage	int $pageIndex	Filtre les placements par indice de page à base zéro	list<PlacedElement>	—	La liste retournée est réindexée.
LayoutResult::isEmpty	—	Vrai lorsqu’aucun élément n’a été placé	bool	—	Vrai pour une entrée vide ou composée uniquement de sauts.
PageBreakStrategy	cas d’énumération Greedy, AvoidOrphans, KeepTogether	Adossé à des chaînes : greedy, avoid_orphans, keep_together	—	—	—
PageBreakStrategy::label	—	Libellé de stratégie lisible par un humain	string	—	—
PlacedElement::__construct	FlowElement $element, int $pageIndex, float $x, float $y, float $width, float $height	Enregistrement de placement immuable	PlacedElement	—	Les coordonnées sont en points, origine en haut à gauche.

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

Contrat de comportement

StreamingLayoutEngine::layout() effectue une seule passe vers l’avant sur la liste d’entrée. Pour chaque élément, il vérifie l’ajustement, effectue un saut de page si nécessaire, puis enregistre un PlacedElement. Une liste d’entrée vide retourne un LayoutResult sans placement, avec un nombre de pages de 1 et une hauteur totale de 0.

La géométrie de placement est déterministe :

• x est le bord gauche de la région.
• y est la position actuelle du curseur plus la marge haute de l’élément.
• width est le widthPt de l’élément lorsqu’il est positif, sinon la largeur de la région.
• height est le heightPt de l’élément, exactement tel que fourni.

Après chaque placement, le curseur avance de totalHeight(), marges incluses. La même quantité s’accumule dans LayoutResult::totalHeightPt.

Règles de saut de page, dans l’ordre d’évaluation :

• Un élément PageBreak explicite incrémente l’indice de page et réinitialise le curseur au sommet de la région. Il n’émet aucun placement et n’ajoute rien à la hauteur totale.
• Lorsque le totalHeight() d’un élément dépasse la hauteur restante, le moteur effectue un saut — sauf si le curseur est déjà au sommet de la page.
• Greedy n’ajoute aucune condition supplémentaire : les éléments qui tiennent sont toujours placés.
• AvoidOrphans effectue un saut avant un élément qui tient lorsque l’espace restant après placement serait positif mais inférieur à la moitié de la hauteur requise par l’élément lui-même. La hauteur propre de l’élément est l’unité de référence, avec un diviseur fixe de deux ; aucune métrique de police n’intervient. Il n’effectue jamais de saut au sommet d’une page.
• KeepTogether effectue un saut avant un élément qui tient lorsque son indicateur keepWithNext est activé, qu’un élément suivant existe, que le curseur n’est pas au sommet de la page et que le totalHeight() combiné des deux éléments dépasse l’espace restant. L’indicateur sur le dernier élément n’a aucun effet.

Placement atomique : le moteur place chaque élément comme une unité. Il ne scinde jamais le contenu d’un élément sur plusieurs pages. FlowElementType::isBreakable() classe les types qu’un appelant peut pré-scinder en éléments plus petits ; le moteur lui-même ne le consulte pas.

Absence d’état et déterminisme : le moteur ne détient que sa région et sa stratégie. layout() ne partage aucun état entre les appels, et des entrées identiques produisent des résultats identiques. withStrategy() et withRegion() retournent de nouveaux moteurs et ne modifient jamais le récepteur.

Cas limites et modes de défaillance

• Aucune méthode de ce module ne lève d’exception. Il n’existe aucune hiérarchie d’exceptions à intercepter.
• Les constructeurs ne valident rien. Les dimensions de région nulles ou négatives, les hauteurs d’élément négatives et les marges négatives sont acceptées et traversent le calcul sans modification.
• Un élément plus haut que la région est tout de même placé. Au sommet d’une page, il y est placé et déborde ; ailleurs, le moteur effectue d’abord un saut et il déborde sur une nouvelle page. L’élément suivant déclenche alors toujours un saut, de sorte que le débordement reste confiné à une seule page.
• Un PageBreak en tête place le premier élément de contenu sur l’indice de page 1, donnant un nombre de pages d’au moins 2.
• Des éléments PageBreak consécutifs font chacun avancer le compteur de pages, produisant des pages vierges. Un PageBreak final laisse une dernière page vide dans pageCount.
• Le maintien groupé ne tient que lorsque les deux éléments appariés tiennent ensemble sur une seule page. Une paire dont la hauteur combinée dépasse une page entière est tout de même scindée.
• Un widthPt non positif se résout à la largeur de la région ; le test de substitution est strictement supérieur à zéro.
• remainingHeight() peut retourner zéro ou une valeur négative une fois que le curseur a débordé. contains() traite la bordure de la région comme intérieure.
• placementsOnPage() avec un indice hors limites retourne une liste vide.
• Ce module n’effectue aucune opération cryptographique et ne définit aucun comportement propre à FIPS.

Conformité

Flow Layout met en œuvre un comportement de placement défini par NextPDF. Il ne vise aucune norme externe de mise en page ou de typographie, si bien que cette page ne comporte aucune table de citations normatives. Les stratégies de saut de page relèvent de la sémantique NextPDF ; elles ne sont pas des implémentations des propriétés de fragmentation CSS ni d’aucun modèle de maintien XSL-FO. Toutes les dimensions sont exprimées en points, correspondant aux unités consommées par le writer Core.

Ces affirmations décrivent uniquement des capacités. NextPDF ne détient aucune certification de conformité, et aucune revendication de certification n’est faite ni sous-entendue.

Notes de développement

• Mesure le contenu en amont. Le moteur consomme les hauteurs fournies par l’appelant ; il ne dispose d’aucune métrique de police et n’effectue aucune mesure de texte.
• Pré-scinde le texte long ou le contenu de tableau en plusieurs éléments avant la mise en page. Utilise isBreakable() pour décider quels types un découpeur peut scinder.
• Réutilise un seul moteur par géométrie de page. Dérive des variantes à moindre coût avec withStrategy() et withRegion().
• Regroupe la sortie par page avec placementsOnPage() lors d’un rendu page par page.
• La mise en page est une passe unique, linéaire en fonction du nombre d’éléments, et ne conserve aucun arbre de document. Les résultats sont déterministes, ce qui convient aux tests par fichier de référence (golden-file).
• Pour le rendu HTML-vers-PDF, utilise plutôt le pipeline HTML de Core ; ce module n’est pas un moteur HTML ou CSS.

Limite de publication

Cette page documente uniquement le comportement observable de l’extérieur et la surface d’API publique prise en charge. Les chemins d’espaces de noms internes, les classes utilitaires, les tables de mécanismes, les noms de fichiers de runbook et les préfixes de tickets sont hors périmètre.

Voir aussi

• Flow Layout — présentation de la fonctionnalité
• Document — référence détaillée
• Module HTML de Core