Flow Layout

Visão geral

O NextPDF Pro posiciona uma sequência de elementos de fluxo — texto, imagens, tabelas, espaçadores — em páginas, atribuindo a cada um uma página e uma posição concretas. O comportamento de quebra de página é selecionável: greedy, com prevenção de órfãos ou manter-junto.

Disponibilidade e licenciamento

Esse recurso é distribuído no NextPDF Pro (nextpdf/pro) e é ativado com um envelope de licença de nível Pro. Uma implantação sem essa habilitação não carrega as classes do recurso. Não há sinalizador de licença separado por recurso; o envelope Pro o habilita. Compare as edições e obtenha uma licença.

Instalação

composer require nextpdf/pro:^3

Visão conceitual

O mecanismo de layout em streaming recebe uma lista de elementos de fluxo e uma região de conteúdo, depois percorre os elementos em ordem e atribui a cada um uma página e uma posição. Quando um elemento não cabe no espaço vertical restante, o mecanismo inicia uma nova página de acordo com a estratégia configurada:

• StreamingLayoutEngine — o mecanismo. Construído com uma LayoutRegion (a área de conteúdo por página) e uma PageBreakStrategy. Ele retorna um LayoutResult de elementos posicionados.
• FlowElement / FlowElementType — o modelo de elemento. Texto e tabelas podem quebrar entre páginas; o mecanismo posiciona imagens e espaçadores de forma atômica.
• PageBreakStrategy — um enum com três comportamentos:
  • Greedy — quebra assim que o próximo elemento não couber.
  • AvoidOrphans — quebra cedo quando resta apenas uma pequena quantidade de espaço, para evitar deixar um único elemento no topo de uma nova página.
  • KeepTogether — honra o sinalizador keep-with-next para que elementos emparelhados permaneçam na mesma página quando possível.

O Flow Layout é um mecanismo de posicionamento de elementos. Ele calcula as atribuições de página e posição; ele não é um mecanismo de renderização de HTML ou CSS. Para HTML-para-PDF, use o pipeline HTML do Core.

Por que funciona assim

O mecanismo atribui a cada elemento uma página e uma posição em uma única passagem para a frente. Ele nunca acumula uma árvore completa do documento para reposicionar depois. Isso mantém a memória limitada por mais longo que o documento seja, e torna o custo linear na contagem de elementos. Cada decisão de quebra de página é um predicado local sobre o cursor atual e a estratégia escolhida. Assim, greedy, prevenção de órfãos e manter-junto se resolvem todos dentro da mesma passagem em streaming. A contrapartida é o comprometimento antecipado: um elemento alto demais transborda em vez de redimensionar, e o manter-junto só vale quando ambos os elementos emparelhados compartilham uma página.

Contexto de projeto: Geração de documentos em alto volume.

Superfície da API

Classe	Responsabilidade
StreamingLayoutEngine	Atribuir páginas e posições a elementos de fluxo.
FlowElement, FlowElementType	Modelo de elemento e enum de tipo.
LayoutRegion	Área de conteúdo por página.
PageBreakStrategy	Enum de comportamento de quebra de página.
LayoutResult, PlacedElement	Saída de posicionamento.

Exemplo de código — Início rápido

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

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

Exemplo de código — Produção

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

Casos extremos e armadilhas

• O mecanismo ainda posiciona um elemento mais alto que a região, mas ele pode transbordar; dimensione os elementos dentro da altura da região.
• KeepTogether mantém os pares juntos apenas quando ambos cabem em uma página.
• AvoidOrphans reserva pelo menos duas alturas de elemento antes de quebrar.

Desempenho

O layout é linear no número de elementos. O mecanismo é em streaming: ele não retém uma árvore completa do documento.

Notas de segurança

O Flow Layout opera sobre os metadados de elementos que você fornece. Ele não realiza nenhuma E/S.

Conformidade

O Flow Layout implementa o comportamento de posicionamento do NextPDF; ele não tem como alvo nenhum padrão de layout externo.

Contrato de comportamento

• StreamingLayoutEngine é construído com uma LayoutRegion e uma PageBreakStrategy e retorna um LayoutResult de elementos posicionados com atribuições concretas de página e posição.
• PageBreakStrategy tem três comportamentos: Greedy (quebra quando o próximo elemento não cabe), AvoidOrphans (quebra cedo, reservando pelo menos duas alturas de elemento) e KeepTogether (honra keep-with-next para que elementos emparelhados permaneçam em uma página quando ambos cabem).
• Texto e tabelas podem quebrar entre páginas; imagens e espaçadores são posicionados de forma atômica. Um elemento mais alto que a região ainda é posicionado, mas pode transbordar.
• O mecanismo é em streaming: ele não retém uma árvore completa do documento e não realiza nenhuma E/S.
• Este é um mecanismo de posicionamento de elementos. Ele calcula as atribuições de página e posição; ele não é um mecanismo de renderização de HTML ou CSS.

Nota sobre o limite do Enterprise

O Enterprise não altera o comportamento do Flow Layout. O Enterprise acrescenta recursos de nível superior documentados separadamente; eles não são necessários para usar o mecanismo de posicionamento.

Alternativa/fallback do Core

Não há mecanismo de posicionamento de elementos no Core com estratégias de quebra de página. Para renderização HTML-para-PDF, use o pipeline HTML do Core open-source. Consulte /modules/html/.

Limite de publicação

Esta página documenta apenas o comportamento observável externamente e a superfície pública de API suportada. Caminhos de namespace internos, classes helper, tabelas de mecanismos, nomes de arquivos de runbook e prefixos de tíquetes estão fora do escopo.

Veja também

• Flow Layout — Referência aprofundada — referência completa de classes e métodos.
• Document — montagem de documentos.
• Módulo HTML do Core — renderização HTML-para-PDF.