Flow Layout — Referensi Mendalam

Sekilas

Halaman ini adalah referensi mendalam untuk modul Pro Flow Layout. Halaman ini mencakup mesin penempatan, model elemen, strategi pemutusan halaman, kontrak perilakunya, dan mode kegagalannya. StreamingLayoutEngine menelusuri daftar nilai FlowElement secara berurutan. Ia menetapkan pada masing-masing sebuah indeks halaman berbasis nol dan sebuah posisi di dalam sebuah LayoutRegion. Hasilnya adalah sebuah LayoutResult berupa record PlacedElement yang immutable. Modul ini hanya menghitung penempatan; ia tidak merender apa pun dan tidak melakukan I/O.

Ketersediaan & lisensi

Kapabilitas ini hadir dalam NextPDF Pro (nextpdf/pro) dan aktif dengan sebuah envelope lisensi tier Pro. Sebuah deployment tanpa entitlement tersebut tidak memuat kelas-kelas kapabilitas ini. Bandingkan edisi dan dapatkan lisensi.

Tidak ada flag lisensi per-fitur. Ini adalah kapabilitas edisi Pro.

Permukaan API publik

Semua simbol berada dalam namespace NextPDF\Pro\FlowLayout. Semua value object bersifat final dan immutable.

Symbol	Parameters	Default behavior	Returns	Throws or fails with	Notes
StreamingLayoutEngine::__construct	LayoutRegion $region, PageBreakStrategy $strategy = PageBreakStrategy::Greedy	Mengikat area konten per-halaman ke sebuah strategi pemutusan	StreamingLayoutEngine	—	Strategi bawaannya adalah Greedy.
StreamingLayoutEngine::layout	list<FlowElement> $elements	Satu lintasan maju; penempatan berurutan dengan pemutusan halaman yang digerakkan strategi	LayoutResult	Tidak pernah throw	Daftar kosong menghasilkan satu halaman kosong.
StreamingLayoutEngine::withStrategy	PageBreakStrategy $strategy	Menurunkan sebuah engine baru dengan region yang sama	self	—	Receiver tidak berubah.
StreamingLayoutEngine::withRegion	LayoutRegion $region	Menurunkan sebuah engine baru dengan strategi yang sama	self	—	Receiver tidak berubah.
FlowElement::__construct	FlowElementType $type, string $content, float $widthPt = 0, float $heightPt = 0, float $marginTopPt = 0, float $marginBottomPt = 0, bool $keepWithNext = false	Value object elemen yang immutable	FlowElement	—	Satu-satunya jalur konstruksi untuk elemen Table.
FlowElement::text	string $content, float $height	Elemen text dengan tinggi yang diukur oleh caller	self (static)	—	Width 0 di-resolve ke lebar region saat penempatan.
FlowElement::image	string $path, float $width, float $height	Elemen image; content membawa path-nya	self (static)	—	Engine tidak pernah membuka file.
FlowElement::spacer	float $height	Whitespace vertikal dengan content kosong	self (static)	—	—
FlowElement::pageBreak	—	Penanda pemutusan eksplisit	self (static)	—	Tidak memancarkan PlacedElement.
FlowElement::totalHeight	—	Tinggi ditambah margin atas dan bawah	float	—	Semua pemeriksaan kecukupan menggunakan nilai ini.
FlowElementType	case enum Text, Image, Table, Spacer, PageBreak	Berbasis string: text, image, table, spacer, page_break	—	—	—
FlowElementType::isBreakable	—	Text dan Table mengembalikan true; lainnya mengembalikan false	bool	—	Klasifikasi saja; lihat kontrak penempatan atomik di bawah.
LayoutRegion::__construct	float $x, float $y, float $width, float $height	Kotak konten beranchor kiri-atas, diukur dalam point	LayoutRegion	—	Tanpa validasi; nilai diterima apa adanya.
LayoutRegion::contains	float $px, float $py	Uji titik-dalam-region yang inklusif terhadap batas	bool	—	—
LayoutRegion::remainingHeight	float $currentY	Tinggi region dikurangi offset vertikal yang terpakai	float	—	Nol atau negatif setelah kursor meluap.
LayoutResult::__construct	list<PlacedElement> $placements, int $pageCount, float $totalHeightPt	Hasil layout yang immutable	LayoutResult	—	—
LayoutResult::placementsOnPage	int $pageIndex	Menyaring penempatan berdasarkan indeks halaman berbasis nol	list<PlacedElement>	—	Daftar yang dikembalikan diindeks ulang.
LayoutResult::isEmpty	—	True ketika tidak ada elemen yang ditempatkan	bool	—	True untuk input kosong dan input hanya berisi pemutusan.
PageBreakStrategy	case enum Greedy, AvoidOrphans, KeepTogether	Berbasis string: greedy, avoid_orphans, keep_together	—	—	—
PageBreakStrategy::label	—	Label strategi yang terbaca manusia	string	—	—
PlacedElement::__construct	FlowElement $element, int $pageIndex, float $x, float $y, float $width, float $height	Record penempatan yang immutable	PlacedElement	—	Koordinat dalam point, beranchor kiri-atas.

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

Kontrak perilaku

StreamingLayoutEngine::layout() melakukan satu lintasan maju atas daftar input. Untuk setiap elemen ia memeriksa kecukupan, memutus halaman ketika diperlukan, lalu mencatat sebuah PlacedElement. Daftar input yang kosong mengembalikan sebuah LayoutResult tanpa penempatan, dengan page count 1, dan total height 0.

Geometri penempatan bersifat deterministik:

• x adalah tepi kiri region.
• y adalah posisi kursor saat ini ditambah margin atas elemen.
• width adalah widthPt elemen ketika positif, jika tidak maka lebar region.
• height adalah heightPt elemen, persis sebagaimana diberikan.

Setelah setiap penempatan kursor maju sebesar totalHeight(), termasuk margin. Jumlah yang sama terakumulasi ke dalam LayoutResult::totalHeightPt.

Aturan pemutusan halaman, dalam urutan evaluasi:

• Sebuah elemen PageBreak eksplisit menaikkan indeks halaman dan mereset kursor ke bagian atas region. Ia tidak memancarkan penempatan dan tidak menambah apa pun ke total height.
• Ketika totalHeight() sebuah elemen melampaui tinggi yang tersisa, engine memutus — kecuali kursor sudah berada di bagian atas halaman.
• Greedy tidak menambah kondisi lebih lanjut: elemen yang muat selalu ditempatkan.
• AvoidOrphans memutus sebelum sebuah elemen yang muat ketika ruang yang tersisa setelah penempatan akan positif namun di bawah setengah tinggi yang dibutuhkan elemen itu sendiri. Tinggi elemen itu sendiri adalah unit acuan, dengan pembagi tetap dua; tidak ada metrik font yang terlibat. Ia tidak pernah memutus di bagian atas sebuah halaman.
• KeepTogether memutus sebelum sebuah elemen yang muat ketika flag keepWithNext-nya di-set, ada elemen berikutnya, kursor tidak berada di bagian atas halaman, dan gabungan totalHeight() dari kedua elemen melampaui ruang yang tersisa. Flag pada elemen terakhir tidak berpengaruh.

Penempatan atomik: engine menempatkan setiap elemen sebagai satu unit. Ia tidak pernah memecah content elemen antar halaman. FlowElementType::isBreakable() mengklasifikasikan tipe mana yang boleh dipecah-lebih-dulu oleh caller menjadi elemen-elemen yang lebih kecil; engine itu sendiri tidak mengonsultasikannya.

Kenirstatusan dan determinisme: engine hanya menyimpan region dan strateginya. layout() tidak berbagi state antar pemanggilan, dan input yang identik menghasilkan hasil yang identik. withStrategy() dan withRegion() mengembalikan engine baru dan tidak pernah memutasi receiver.

Kasus tepi & mode kegagalan

• Tidak ada metode dalam modul ini yang throw. Tidak ada hierarki exception untuk ditangkap.
• Konstruktor tidak memvalidasi apa pun. Dimensi region negatif atau nol, tinggi elemen negatif, dan margin negatif diterima dan mengalir melalui aritmatika tanpa perubahan.
• Sebuah elemen yang lebih tinggi daripada region tetap ditempatkan. Di bagian atas sebuah halaman ia ditempatkan di sana dan meluap; di tempat lain engine memutus terlebih dahulu dan ia meluap pada halaman baru. Elemen berikutnya kemudian selalu memicu sebuah pemutusan, sehingga luapan terbatas pada satu halaman.
• Sebuah PageBreak di awal menempatkan elemen content pertama pada indeks halaman 1, memberikan page count sekurang-kurangnya 2.
• Elemen PageBreak yang berurutan masing-masing memajukan penghitung halaman, menghasilkan halaman kosong. Sebuah PageBreak di akhir meninggalkan sebuah halaman kosong terakhir pada pageCount.
• Keep-together hanya berlaku ketika kedua elemen berpasangan muat bersama pada satu halaman. Sebuah pasangan yang gabungan tingginya melampaui satu halaman penuh tetap terpecah.
• Sebuah widthPt non-positif di-resolve ke lebar region; pemeriksaan substitusinya adalah lebih besar dari nol secara ketat.
• remainingHeight() dapat mengembalikan nol atau nilai negatif setelah kursor meluap. contains() memperlakukan batas region sebagai berada di dalam.
• placementsOnPage() dengan indeks di luar rentang mengembalikan daftar kosong.
• Modul ini tidak melakukan operasi kriptografis dan tidak mendefinisikan perilaku khusus FIPS.

Kesesuaian

Flow Layout mengimplementasikan perilaku penempatan yang didefinisikan NextPDF. Ia tidak menargetkan standar tata letak atau tipografi eksternal, sehingga halaman ini tidak membawa tabel sitasi normatif. Strategi pemutusan halaman adalah semantik NextPDF; keduanya bukan implementasi dari properti fragmentasi CSS atau model keep XSL-FO mana pun. Semua dimensi dinyatakan dalam point, sesuai dengan unit yang dikonsumsi oleh Core writer.

Pernyataan-pernyataan ini hanya menjelaskan kapabilitas. NextPDF tidak memegang sertifikasi kesesuaian apa pun, dan tidak ada klaim sertifikasi yang dibuat atau tersirat.

Catatan pengembangan

• Ukur content di hulu. Engine mengonsumsi tinggi yang disuplai caller; ia tidak memiliki metrik font dan tidak melakukan pengukuran teks.
• Pecah-lebih-dulu content text atau table yang panjang menjadi beberapa elemen sebelum layout. Gunakan isBreakable() untuk memutuskan tipe mana yang boleh dipecah oleh sebuah chunker.
• Gunakan ulang satu engine per geometri halaman. Turunkan varian secara murah dengan withStrategy() dan withRegion().
• Kelompokkan keluaran per halaman dengan placementsOnPage() ketika merender halaman demi halaman.
• Layout adalah satu lintasan, linear terhadap jumlah elemen, dan tidak menyimpan pohon dokumen. Hasilnya deterministik, yang cocok untuk pengujian golden-file.
• Untuk perenderan HTML-ke-PDF, gunakan Core HTML pipeline sebagai gantinya; modul ini bukan mesin HTML atau CSS.

Batas publikasi

Halaman ini hanya mendokumentasikan perilaku yang teramati secara eksternal dan permukaan API publik yang didukung. Path namespace internal, kelas helper, tabel mekanisme, nama file runbook, dan prefiks tiket berada di luar cakupan.

Lihat juga

• Flow Layout — ikhtisar kapabilitas
• Document — Referensi Mendalam
• Modul Core HTML