Flow Layout — szczegółowa dokumentacja referencyjna

W skrócie

Ta strona jest szczegółową dokumentacją referencyjną modułu Pro Flow Layout. Obejmuje silnik rozmieszczania, model elementów, strategie łamania stron, ich kontrakty zachowania oraz tryby awarii. StreamingLayoutEngine przechodzi po liście wartości FlowElement w kolejności. Każdej z nich przypisuje liczony od zera indeks strony oraz pozycję wewnątrz LayoutRegion. Wynikiem jest LayoutResult złożony z niemodyfikowalnych rekordów PlacedElement. Moduł wykonuje wyłącznie obliczanie rozmieszczenia; niczego nie renderuje i nie wykonuje żadnych operacji wejścia/wyjścia.

Dostępność i licencjonowanie

Ta funkcjonalność wchodzi w skład NextPDF Pro (nextpdf/pro) i aktywuje się wraz z kopertą licencyjną poziomu Pro. Wdrożenie bez tego uprawnienia nie ładuje klas tej funkcjonalności. Porównaj edycje i uzyskaj licencję.

Nie istnieje flaga licencji dla pojedynczej funkcji. Jest to funkcjonalność edycji Pro.

Powierzchnia publicznego API

Wszystkie symbole znajdują się w przestrzeni nazw NextPDF\Pro\FlowLayout. Wszystkie obiekty wartości są final i niemodyfikowalne.

Symbol	Parametry	Zachowanie domyślne	Zwraca	Zgłasza lub kończy się błędem	Uwagi
StreamingLayoutEngine::__construct	LayoutRegion $region, PageBreakStrategy $strategy = PageBreakStrategy::Greedy	Wiąże obszar treści pojedynczej strony ze strategią łamania	StreamingLayoutEngine	—	Strategia domyślnie przyjmuje Greedy.
StreamingLayoutEngine::layout	list<FlowElement> $elements	Pojedyncze przejście w przód; sekwencyjne rozmieszczanie z łamaniem stron sterowanym strategią	LayoutResult	Nigdy nie zgłasza wyjątku	Pusta lista daje jedną pustą stronę.
StreamingLayoutEngine::withStrategy	PageBreakStrategy $strategy	Wyprowadza nowy silnik z tym samym obszarem	self	—	Odbiorca pozostaje niezmieniony.
StreamingLayoutEngine::withRegion	LayoutRegion $region	Wyprowadza nowy silnik z tą samą strategią	self	—	Odbiorca pozostaje niezmieniony.
FlowElement::__construct	FlowElementType $type, string $content, float $widthPt = 0, float $heightPt = 0, float $marginTopPt = 0, float $marginBottomPt = 0, bool $keepWithNext = false	Niemodyfikowalny obiekt wartości elementu	FlowElement	—	Jedyna ścieżka konstrukcji dla elementów Table.
FlowElement::text	string $content, float $height	Element tekstowy o wysokości zmierzonej przez wywołującego	self (statyczna)	—	Szerokość 0 rozwija się do szerokości obszaru w momencie rozmieszczenia.
FlowElement::image	string $path, float $width, float $height	Element obrazu; content przenosi ścieżkę	self (statyczna)	—	Silnik nigdy nie otwiera pliku.
FlowElement::spacer	float $height	Pionowa przestrzeń pusta z pustą treścią	self (statyczna)	—	—
FlowElement::pageBreak	—	Jawny znacznik łamania	self (statyczna)	—	Nie emituje żadnego PlacedElement.
FlowElement::totalHeight	—	Wysokość powiększona o margines górny i dolny	float	—	Wszystkie sprawdzenia dopasowania używają tej wartości.
FlowElementType	przypadki enuma Text, Image, Table, Spacer, PageBreak	Oparty na łańcuchach: text, image, table, spacer, page_break	—	—	—
FlowElementType::isBreakable	—	Text i Table zwracają true; pozostałe zwracają false	bool	—	Wyłącznie klasyfikacja; zobacz kontrakt rozmieszczania atomowego poniżej.
LayoutRegion::__construct	float $x, float $y, float $width, float $height	Prostokąt treści z początkiem w lewym górnym rogu, mierzony w punktach	LayoutRegion	—	Brak walidacji; wartości przyjmowane są bez zmian.
LayoutRegion::contains	float $px, float $py	Test przynależności punktu do obszaru z granicą włączoną	bool	—	—
LayoutRegion::remainingHeight	float $currentY	Wysokość obszaru pomniejszona o wykorzystane przesunięcie pionowe	float	—	Zero lub wartość ujemna, gdy kursor przekroczył granicę.
LayoutResult::__construct	list<PlacedElement> $placements, int $pageCount, float $totalHeightPt	Niemodyfikowalny wynik rozmieszczenia	LayoutResult	—	—
LayoutResult::placementsOnPage	int $pageIndex	Filtruje rozmieszczenia według liczonego od zera indeksu strony	list<PlacedElement>	—	Zwracana lista jest ponownie indeksowana.
LayoutResult::isEmpty	—	True, gdy nie rozmieszczono żadnego elementu	bool	—	True dla wejścia pustego oraz zawierającego wyłącznie łamania.
PageBreakStrategy	przypadki enuma Greedy, AvoidOrphans, KeepTogether	Oparty na łańcuchach: greedy, avoid_orphans, keep_together	—	—	—
PageBreakStrategy::label	—	Czytelna dla człowieka etykieta strategii	string	—	—
PlacedElement::__construct	FlowElement $element, int $pageIndex, float $x, float $y, float $width, float $height	Niemodyfikowalny rekord rozmieszczenia	PlacedElement	—	Współrzędne są w punktach, początek w lewym górnym rogu.

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

Kontrakt zachowania

StreamingLayoutEngine::layout() wykonuje jedno przejście w przód po liście wejściowej. Dla każdego elementu sprawdza dopasowanie, w razie potrzeby łamie stronę, a następnie zapisuje PlacedElement. Pusta lista wejściowa zwraca LayoutResult bez rozmieszczeń, z liczbą stron równą 1 oraz łączną wysokością 0.

Geometria rozmieszczenia jest deterministyczna:

• x to lewa krawędź obszaru.
• y to bieżąca pozycja kursora powiększona o margines górny elementu.
• width to widthPt elementu, gdy jest dodatnie, w przeciwnym razie szerokość obszaru.
• height to heightPt elementu, dokładnie tak jak podano.

Po każdym rozmieszczeniu kursor przesuwa się o totalHeight(), wraz z marginesami. Ta sama wartość sumuje się do LayoutResult::totalHeightPt.

Reguły łamania stron, w kolejności obliczania:

• Jawny element PageBreak zwiększa indeks strony i przywraca kursor do góry obszaru. Nie emituje żadnego rozmieszczenia i niczego nie dodaje do łącznej wysokości.
• Gdy totalHeight() elementu przekracza pozostałą wysokość, silnik łamie stronę — chyba że kursor znajduje się już na górze strony.
• Greedy nie dodaje żadnego dalszego warunku: mieszczące się elementy są zawsze rozmieszczane.
• AvoidOrphans łamie stronę przed mieszczącym się elementem, gdy przestrzeń pozostała po rozmieszczeniu byłaby dodatnia, lecz mniejsza niż połowa własnej wymaganej wysokości elementu. Jednostką odniesienia jest własna wysokość elementu, ze stałym dzielnikiem równym dwa; nie uczestniczy w tym żadna metryka czcionki. Nigdy nie łamie na górze strony.
• KeepTogether łamie stronę przed mieszczącym się elementem, gdy jego flaga keepWithNext jest ustawiona, istnieje następny element, kursor nie znajduje się na górze strony, a łączna wartość totalHeight() obu elementów przekracza pozostałą przestrzeń. Flaga na ostatnim elemencie nie ma żadnego efektu.

Rozmieszczanie atomowe: silnik rozmieszcza każdy element jako całość. Nigdy nie dzieli treści elementu między strony. FlowElementType::isBreakable() klasyfikuje, które typy wywołujący może wstępnie podzielić na mniejsze elementy; sam silnik z niego nie korzysta.

Bezstanowość i determinizm: silnik przechowuje wyłącznie swój obszar i strategię. layout() nie dzieli żadnego stanu między wywołaniami, a identyczne dane wejściowe dają identyczne wyniki. withStrategy() i withRegion() zwracają nowe silniki i nigdy nie modyfikują odbiorcy.

Przypadki brzegowe i tryby awarii

• Żadna metoda w tym module nie zgłasza wyjątku. Nie istnieje hierarchia wyjątków do przechwycenia.
• Konstruktory niczego nie walidują. Ujemne lub zerowe wymiary obszaru, ujemne wysokości elementów oraz ujemne marginesy są akceptowane i przepływają przez arytmetykę bez zmian.
• Element wyższy niż obszar jest mimo to rozmieszczany. Na górze strony jest rozmieszczany w tym miejscu i wykracza poza granice; w innym miejscu silnik najpierw łamie stronę, a element wykracza poza świeżą stronę. Kolejny element zawsze wywołuje wtedy łamanie, więc przekroczenie granic jest ograniczone do jednej strony.
• Wiodący PageBreak rozmieszcza pierwszy element treści na stronie o indeksie 1, dając liczbę stron równą co najmniej 2.
• Kolejne po sobie elementy PageBreak zwiększają licznik stron, tworząc puste strony. Końcowy pozostawia ostatnią pustą stronę w pageCount.
• Keep-together obowiązuje tylko wtedy, gdy oba sparowane elementy mieszczą się razem na jednej stronie. Para, której łączna wysokość przekracza pełną stronę, i tak zostaje podzielona.
• Niedodatnie widthPt rozwija się do szerokości obszaru; sprawdzenie podstawienia jest ściśle większe od zera.
• remainingHeight() może zwrócić zero lub wartość ujemną, gdy kursor przekroczył granicę. contains() traktuje granicę obszaru jako należącą do wnętrza.
• placementsOnPage() z indeksem poza zakresem zwraca pustą listę.
• Ten moduł nie wykonuje żadnych operacji kryptograficznych i nie definiuje żadnego zachowania właściwego dla FIPS.

Zgodność ze standardami

Flow Layout implementuje zachowanie rozmieszczania zdefiniowane przez NextPDF. Nie celuje w żaden zewnętrzny standard układu ani typografii, więc ta strona nie zawiera tabeli odniesień normatywnych. Strategie łamania stron to semantyka NextPDF; nie są implementacjami właściwości fragmentacji CSS ani żadnego modelu keep z XSL-FO. Wszystkie wymiary wyrażone są w punktach, zgodnie z jednostkami, które przyjmuje moduł zapisu Core.

Te stwierdzenia opisują wyłącznie możliwości. NextPDF nie posiada żadnej certyfikacji zgodności i nie formułuje ani nie sugeruje żadnego roszczenia certyfikacyjnego.

Uwagi programistyczne

• Zmierz treść na wcześniejszym etapie. Silnik przyjmuje wysokości dostarczone przez wywołującego; nie ma metryk czcionek i nie wykonuje pomiaru tekstu.
• Wstępnie podziel długą treść tekstową lub tabelaryczną na wiele elementów przed rozmieszczeniem. Użyj isBreakable(), aby zdecydować, które typy może dzielić mechanizm dzielący.
• Używaj ponownie jednego silnika na daną geometrię strony. Wyprowadzaj warianty tanio za pomocą withStrategy() i withRegion().
• Grupuj wynik według stron za pomocą placementsOnPage() przy renderowaniu strona po stronie.
• Rozmieszczanie to pojedyncze przejście, liniowe względem liczby elementów, i nie zachowuje drzewa dokumentu. Wyniki są deterministyczne, co sprzyja testom typu golden-file.
• Do renderowania HTML-do-PDF użyj zamiast tego potoku HTML modułu Core; ten moduł nie jest silnikiem HTML ani CSS.

Granica publikacji

Ta strona dokumentuje wyłącznie zachowanie obserwowalne z zewnątrz oraz wspieraną powierzchnię publicznego 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 także

• Flow Layout — przegląd funkcjonalności
• Document — szczegółowa dokumentacja referencyjna
• Moduł Core HTML