Layout a flusso

In sintesi

NextPDF Pro posiziona una sequenza di elementi a flusso — testo, immagini, tabelle, spaziatori — sulle pagine, assegnando a ciascuno una pagina e una posizione concrete. Il comportamento di interruzione di pagina è selezionabile: greedy, con evitamento degli orfani o keep-together.

Disponibilità e licenza

Questa funzionalità è fornita in NextPDF Pro (nextpdf/pro) e si attiva con un envelope di licenza di livello Pro. Un deployment privo di tale entitlement non carica le classi della funzionalità. Non esiste un flag di licenza separato per singola funzionalità; è l’envelope Pro ad abilitarla. Confronta le edizioni e ottieni una licenza.

Installazione

composer require nextpdf/pro:^3

Panoramica concettuale

Il motore di layout in streaming prende un elenco di elementi a flusso e una regione di contenuto, quindi percorre gli elementi in ordine e assegna a ciascuno una pagina e una posizione. Quando un elemento non entra nello spazio verticale rimanente, il motore avvia una nuova pagina secondo la strategia configurata:

• StreamingLayoutEngine — il motore. Costruito con una LayoutRegion (l’area di contenuto per pagina) e una PageBreakStrategy. Restituisce un LayoutResult di elementi posizionati.
• FlowElement / FlowElementType — il modello degli elementi. Testo e tabelle possono interrompersi tra le pagine; il motore posiziona immagini e spaziatori in modo atomico.
• PageBreakStrategy — un’enumerazione con tre comportamenti:
  • Greedy — interrompe non appena l’elemento successivo non entra.
  • AvoidOrphans — interrompe in anticipo quando rimane solo una piccola quantità di spazio, per evitare di lasciare un singolo elemento in cima a una nuova pagina.
  • KeepTogether — rispetta il flag keep-with-next, così che gli elementi accoppiati restino sulla stessa pagina quando possibile.

Flow Layout è un motore di posizionamento di elementi. Calcola le assegnazioni di pagina e posizione; non è un motore di rendering di HTML o CSS. Per la conversione da HTML a PDF, usare la pipeline HTML del Core.

Perché funziona così

Il motore assegna a ogni elemento una pagina e una posizione in un’unica passata in avanti. Non bufferizza mai un intero albero di documento per rifluirlo successivamente. Ciò mantiene la memoria limitata per quanto lungo sia il documento e rende il costo lineare rispetto al numero di elementi. Ogni decisione di interruzione di pagina è un predicato locale sul cursore corrente e sulla strategia scelta. Quindi greedy, evitamento degli orfani e keep-together si risolvono tutti all’interno della stessa passata in streaming. Il compromesso è l’impegno in avanti: un elemento eccessivamente alto trabocca invece di riscalarsi, e keep-together vale solo quando entrambi gli elementi accoppiati condividono una pagina.

Contesto di progettazione: Generazione di documenti ad alto volume.

Superficie API

Class	Responsibility
StreamingLayoutEngine	Assegnare pagine e posizioni agli elementi a flusso.
FlowElement, FlowElementType	Modello degli elementi ed enumerazione dei tipi.
LayoutRegion	Area di contenuto per pagina.
PageBreakStrategy	Enumerazione del comportamento di interruzione di pagina.
LayoutResult, PlacedElement	Output del posizionamento.

Esempio di codice — Avvio rapido

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

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

Esempio di codice — Produzione

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

Casi limite e insidie

• Il motore posiziona comunque un elemento più alto della regione, ma può traboccare; dimensionare gli elementi entro l’altezza della regione.
• KeepTogether mantiene le coppie unite solo quando entrambe entrano in una sola pagina.
• AvoidOrphans riserva almeno due altezze di elemento prima di interrompere.

Prestazioni

Il layout è lineare rispetto al numero di elementi. Il motore è in streaming: non conserva un albero di documento completo.

Note sulla sicurezza

Flow Layout opera sui metadati degli elementi forniti dall’utente. Non esegue alcun I/O.

Conformità

Flow Layout implementa il comportamento di posizionamento di NextPDF; non punta a uno standard di layout esterno.

Contratto di comportamento

• StreamingLayoutEngine viene costruito con una LayoutRegion e una PageBreakStrategy e restituisce un LayoutResult di elementi posizionati con assegnazioni di pagina e posizione concrete.
• PageBreakStrategy ha tre comportamenti: Greedy (interrompe quando l’elemento successivo non entra), AvoidOrphans (interrompe in anticipo, riservando almeno due altezze di elemento) e KeepTogether (rispetta keep-with-next, così che gli elementi accoppiati restino su una sola pagina quando entrambi entrano).
• Testo e tabelle possono interrompersi tra le pagine; immagini e spaziatori vengono posizionati in modo atomico. Un elemento più alto della regione viene comunque posizionato ma può traboccare.
• Il motore è in streaming: non conserva un albero di documento completo e non esegue alcun I/O.
• Questo è un motore di posizionamento di elementi. Calcola le assegnazioni di pagina e posizione; non è un motore di rendering di HTML o CSS.

Nota sul confine Enterprise

Enterprise non modifica il comportamento di Flow Layout. Enterprise aggiunge funzionalità di fascia superiore documentate separatamente; non sono richieste per usare il motore di posizionamento.

Core fallback / alternativa

Non esiste alcun motore di posizionamento di elementi del Core con strategie di interruzione di pagina. Per il rendering da HTML a PDF, usare la pipeline HTML del Core open source. Vedere /modules/html/.

Confine di pubblicazione

Questa pagina documenta solo il comportamento osservabile dall’esterno e la superficie API pubblica supportata. Percorsi di namespace interni, classi helper, tabelle dei meccanismi, nomi di file di runbook e prefissi di ticket sono fuori ambito.

Vedere anche

• Flow Layout — Deep Reference — riferimento completo di classi e metodi.
• Document — assemblaggio dei documenti.
• Core HTML module — rendering da HTML a PDF.