Układ przepływowy

W skrócie

NextPDF Pro rozmieszcza sekwencję elementów przepływu — tekst, obrazy, tabele, odstępy — na stronach, przypisując każdemu konkretną stronę i pozycję. Zachowanie podziału stron jest wybieralne: zachłanne, unikające sierot lub trzymające razem.

Dostępność i licencjonowanie

Ta funkcja dostarczana jest w NextPDF Pro (nextpdf/pro) i aktywuje się za pomocą koperty licencyjnej poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcji. Nie ma osobnej flagi licencyjnej dla poszczególnych funkcji; koperta Pro ją włącza. Porównaj edycje i uzyskaj licencję.

Instalacja

composer require nextpdf/pro:^3

Przegląd koncepcyjny

Strumieniowy silnik układu przyjmuje listę elementów przepływu oraz region zawartości, następnie przechodzi elementy po kolei i przypisuje każdemu stronę i pozycję. Gdy element nie mieści się w pozostałej przestrzeni pionowej, silnik rozpoczyna nową stronę zgodnie ze skonfigurowaną strategią:

• StreamingLayoutEngine — silnik. Konstruowany z LayoutRegion (obszar zawartości na stronę) oraz PageBreakStrategy. Zwraca LayoutResult rozmieszczonych elementów.
• FlowElement / FlowElementType — model elementu. Tekst i tabele mogą łamać się przez strony; silnik rozmieszcza obrazy i odstępy atomowo.
• PageBreakStrategy — enum z trzema zachowaniami:
  • Greedy — łam, gdy tylko następny element się nie mieści.
  • AvoidOrphans — łam wcześnie, gdy pozostaje tylko niewielka ilość miejsca, aby uniknąć pozostawienia pojedynczego elementu na górze nowej strony.
  • KeepTogether — uszanuj flagę keep-with-next, aby sparowane elementy pozostawały na tej samej stronie, gdy to możliwe.

Flow Layout to silnik rozmieszczania elementów. Oblicza przypisania stron i pozycji; nie jest silnikiem renderowania HTML ani CSS. Do HTML-do-PDF użyj potoku HTML z Core.

Dlaczego działa to w ten sposób

Silnik przypisuje każdemu elementowi stronę i pozycję w jednym przejściu do przodu. Nigdy nie buforuje pełnego drzewa dokumentu, by przelać je później. Utrzymuje to ograniczone zużycie pamięci niezależnie od długości dokumentu i sprawia, że koszt jest liniowy względem liczby elementów. Każda decyzja o podziale strony to lokalny predykat na bieżącym kursorze i wybranej strategii. Dzięki temu zachłanność, unikanie sierot oraz trzymanie razem rozstrzygają się w tym samym strumieniowym przejściu. Kompromisem jest zobowiązanie do przodu: zbyt wysoki element przekracza obszar, zamiast się przeskalować, a trzymanie razem obowiązuje tylko wtedy, gdy oba sparowane elementy dzielą stronę.

Tło projektowe: Generowanie dokumentów o dużej objętości.

Powierzchnia API

Klasa	Odpowiedzialność
StreamingLayoutEngine	Przypisz strony i pozycje elementom przepływu.
FlowElement, FlowElementType	Model elementu i enum typu.
LayoutRegion	Obszar zawartości na stronę.
PageBreakStrategy	Enum zachowania podziału stron.
LayoutResult, PlacedElement	Wyjście rozmieszczenia.

Przykład kodu — Szybki start

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

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

Przykład kodu — Produkcja

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

Przypadki brzegowe i pułapki

• Silnik nadal rozmieszcza element wyższy niż region, ale może on przekroczyć obszar; dopasuj rozmiar elementów do wysokości regionu.
• KeepTogether trzyma pary razem tylko wtedy, gdy obie mieszczą się na jednej stronie.
• AvoidOrphans rezerwuje co najmniej dwie wysokości elementów przed łamaniem.

Wydajność

Układ jest liniowy względem liczby elementów. Silnik jest strumieniowy: nie zachowuje pełnego drzewa dokumentu.

Uwagi dotyczące bezpieczeństwa

Flow Layout operuje na dostarczanych przez Ciebie metadanych elementów. Nie wykonuje żadnego wejścia/wyjścia.

Konformancja

Flow Layout implementuje zachowanie rozmieszczania NextPDF; nie celuje w żaden zewnętrzny standard układu.

Kontrakt zachowania

• StreamingLayoutEngine jest konstruowany z LayoutRegion oraz PageBreakStrategy i zwraca LayoutResult rozmieszczonych elementów z konkretnymi przypisaniami strony i pozycji.
• PageBreakStrategy ma trzy zachowania: Greedy (łam, gdy następny element się nie mieści), AvoidOrphans (łam wcześnie, rezerwując co najmniej dwie wysokości elementów) oraz KeepTogether (uszanuj keep-with-next, aby sparowane elementy pozostawały na jednej stronie, gdy obie się mieszczą).
• Tekst i tabele mogą łamać się przez strony; obrazy i odstępy są rozmieszczane atomowo. Element wyższy niż region jest nadal rozmieszczany, ale może przekroczyć obszar.
• Silnik jest strumieniowy: nie zachowuje pełnego drzewa dokumentu i nie wykonuje żadnego wejścia/wyjścia.
• To silnik rozmieszczania elementów. Oblicza przypisania stron i pozycji; nie jest silnikiem renderowania HTML ani CSS.

Nota o granicy Enterprise

Enterprise nie zmienia zachowania Flow Layout. Enterprise dodaje funkcje wyższego poziomu udokumentowane osobno; nie są one wymagane do korzystania z silnika rozmieszczania.

Rozwiązanie awaryjne / alternatywa w Core

Nie istnieje w Core silnik rozmieszczania elementów ze strategiami podziału stron. Do renderowania HTML-do-PDF użyj otwartoźródłowego potoku HTML z Core. Zobacz /modules/html/.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne zewnętrznie oraz obsługiwaną publiczną powierzchnię API. Wewnętrzne ścieżki przestrzeni nazw, klasy pomocnicze, tabele mechanizmów, nazwy plików runbooków oraz prefiksy zgłoszeń są poza zakresem.

Zobacz też

• Flow Layout — Deep Reference — pełna dokumentacja klas i metod.
• Document — składanie dokumentów.
• Core HTML module — renderowanie HTML-do-PDF.