Flow Layout — Derinlemesine başvuru

Bir bakışta

Bu sayfa, Pro Flow Layout modülünün derinlemesine başvurusudur. Yerleştirme motorunu, öğe modelini, sayfa sonu stratejilerini, bunların davranış sözleşmelerini ve hata modlarını kapsar. StreamingLayoutEngine, bir FlowElement değerleri listesini sırayla gezer. Her birine sıfır tabanlı bir sayfa dizini ve bir LayoutRegion içinde bir konum atar. Sonuç, değişmez PlacedElement kayıtlarından oluşan bir LayoutResult’tur. Modül yalnızca yerleştirmeyi hesaplar; hiçbir şey işlemez ve hiçbir G/Ç gerçekleştirmez.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile gelir ve bir Pro katmanı lisans zarfıyla etkinleşir. Bu yetkiye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Sürümleri karşılaştırın ve bir lisans edinin.

Özellik başına lisans bayrağı yoktur. Bu bir Pro sürümü yeteneğidir.

Genel API yüzeyi

Tüm semboller NextPDF\Pro\FlowLayout ad alanında bulunur. Tüm değer nesneleri final ve değişmezdir.

Sembol	Parametreler	Varsayılan davranış	Döndürür	Fırlatır veya şununla başarısız olur	Notlar
StreamingLayoutEngine::__construct	LayoutRegion $region, PageBreakStrategy $strategy = PageBreakStrategy::Greedy	Sayfa başına bir içerik alanını bir sonlandırma stratejisine bağlar	StreamingLayoutEngine	—	Strateji varsayılan olarak Greedy’dir.
StreamingLayoutEngine::layout	list<FlowElement> $elements	Tek ileri geçiş; strateji güdümlü sayfa sonlarıyla sıralı yerleştirme	LayoutResult	Asla fırlatmaz	Boş bir liste tek bir boş sayfa verir.
StreamingLayoutEngine::withStrategy	PageBreakStrategy $strategy	Aynı bölgeyle yeni bir motor türetir	self	—	Alıcı değişmez.
StreamingLayoutEngine::withRegion	LayoutRegion $region	Aynı stratejiyle yeni bir motor türetir	self	—	Alıcı değişmez.
FlowElement::__construct	FlowElementType $type, string $content, float $widthPt = 0, float $heightPt = 0, float $marginTopPt = 0, float $marginBottomPt = 0, bool $keepWithNext = false	Değişmez öğe değer nesnesi	FlowElement	—	Table öğeleri için tek yapım yolu.
FlowElement::text	string $content, float $height	Çağıran tarafından ölçülmüş yükseklikli metin öğesi	self (static)	—	Genişlik 0, yerleştirmede bölge genişliğine çözülür.
FlowElement::image	string $path, float $width, float $height	Görüntü öğesi; content yolu taşır	self (static)	—	Motor dosyayı asla açmaz.
FlowElement::spacer	float $height	Boş içerikli dikey boşluk	self (static)	—	—
FlowElement::pageBreak	—	Açık sonlandırma işaretçisi	self (static)	—	Hiçbir PlacedElement yaymaz.
FlowElement::totalHeight	—	Yükseklik artı üst ve alt kenar boşlukları	float	—	Tüm sığma denetimleri bu değeri kullanır.
FlowElementType	enum durumları Text, Image, Table, Spacer, PageBreak	Dize destekli: text, image, table, spacer, page_break	—	—	—
FlowElementType::isBreakable	—	Text ve Table true döndürür; diğerleri false döndürür	bool	—	Yalnızca sınıflandırma; aşağıdaki atomik yerleştirme sözleşmesine bakın.
LayoutRegion::__construct	float $x, float $y, float $width, float $height	Puan cinsinden ölçülmüş, sol-üst orijinli içerik kutusu	LayoutRegion	—	Doğrulama yok; değerler verildiği gibi alınır.
LayoutRegion::contains	float $px, float $py	Sınır dahil nokta-bölge içinde testi	bool	—	—
LayoutRegion::remainingHeight	float $currentY	Bölge yüksekliği eksi tüketilen dikey uzaklık	float	—	İmleç taştıktan sonra sıfır veya negatif.
LayoutResult::__construct	list<PlacedElement> $placements, int $pageCount, float $totalHeightPt	Değişmez yerleşim sonucu	LayoutResult	—	—
LayoutResult::placementsOnPage	int $pageIndex	Yerleştirmeleri sıfır tabanlı sayfa dizinine göre filtreler	list<PlacedElement>	—	Döndürülen liste yeniden dizinlenir.
LayoutResult::isEmpty	—	Hiçbir öğe yerleştirilmediğinde true	bool	—	Boş ve yalnızca sonlandırmalı girdi için true.
PageBreakStrategy	enum durumları Greedy, AvoidOrphans, KeepTogether	Dize destekli: greedy, avoid_orphans, keep_together	—	—	—
PageBreakStrategy::label	—	İnsan tarafından okunabilir strateji etiketi	string	—	—
PlacedElement::__construct	FlowElement $element, int $pageIndex, float $x, float $y, float $width, float $height	Değişmez yerleştirme kaydı	PlacedElement	—	Koordinatlar puan cinsinden, sol-üst orijinlidir.

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

Davranış sözleşmesi

StreamingLayoutEngine::layout(), girdi listesi üzerinde tek bir ileri geçiş gerçekleştirir. Her öğe için sığmayı denetler, gerektiğinde sayfayı sonlandırır, ardından bir PlacedElement kaydeder. Boş bir girdi listesi; hiçbir yerleştirme içermeyen, sayfa sayısı 1 ve toplam yüksekliği 0 olan bir LayoutResult döndürür.

Yerleştirme geometrisi belirlenimcidir:

• x, bölgenin sol kenarıdır.
• y, geçerli imleç konumu artı öğenin üst kenar boşluğudur.
• width, pozitif olduğunda öğenin widthPt’si, aksi hâlde bölge genişliğidir.
• height, tam olarak verildiği gibi öğenin heightPt’sidir.

Her yerleştirmeden sonra imleç, kenar boşlukları dahil totalHeight() kadar ilerler. Aynı miktar LayoutResult::totalHeightPt içinde birikir.

Sayfa sonlandırma kuralları, değerlendirme sırasıyla:

• Açık bir PageBreak öğesi, sayfa dizinini artırır ve imleci bölgenin üstüne sıfırlar. Hiçbir yerleştirme yaymaz ve toplam yüksekliğe hiçbir şey eklemez.
• Bir öğenin totalHeight()’i kalan yüksekliği aştığında motor sonlandırır — imleç zaten sayfanın üstünde değilse.
• Greedy başka bir koşul eklemez: sığan öğeler her zaman yerleştirilir.
• AvoidOrphans, yerleştirmeden sonra kalacak alan pozitif ancak öğenin kendi gereken yüksekliğinin yarısının altında olduğunda, sığan bir öğeden önce sonlandırır. Referans birim, öğenin kendi yüksekliğidir ve sabit iki bölenlidir; hiçbir font metriği söz konusu değildir. Bir sayfanın üstünde asla sonlandırmaz.
• KeepTogether, bir öğenin keepWithNext bayrağı ayarlıysa, bir sonraki öğe varsa, imleç sayfanın üstünde değilse ve her iki öğenin birleşik totalHeight()’i kalan alanı aşıyorsa, sığan öğeden önce sonlandırır. Son öğedeki bayrağın hiçbir etkisi yoktur.

Atomik yerleştirme: motor her öğeyi tek bir birim olarak yerleştirir. Öğe içeriğini asla sayfalar arasında bölmez. FlowElementType::isBreakable(), bir çağıranın hangi türleri daha küçük öğelere önceden bölebileceğini sınıflandırır; motorun kendisi buna başvurmaz.

Durumsuzluk ve belirlenimcilik: motor yalnızca bölgesini ve stratejisini tutar. layout(), çağrılar arasında hiçbir durum paylaşmaz ve özdeş girdiler özdeş sonuçlar üretir. withStrategy() ve withRegion(), yeni motorlar döndürür ve alıcıyı asla değiştirmez.

Uç durumlar ve hata modları

• Bu modülde hiçbir yöntem fırlatmaz. Yakalanacak bir istisna hiyerarşisi yoktur.
• Yapıcılar hiçbir şeyi doğrulamaz. Negatif veya sıfır bölge boyutları, negatif öğe yükseklikleri ve negatif kenar boşlukları kabul edilir ve aritmetikten değişmeden akar.
• Bölgeden daha uzun bir öğe yine de yerleştirilir. Bir sayfanın üstünde oraya yerleştirilir ve taşar; başka yerde ise motor önce sonlandırır ve öğe yeni bir sayfayı taşırır. Bir sonraki öğe ise her zaman bir sonlandırmayı tetikler, böylece taşma tek bir sayfayla sınırlı kalır.
• Baştaki bir PageBreak, ilk içerik öğesini sayfa dizini 1’e yerleştirir ve en az 2’lik bir sayfa sayısı verir.
• Ardışık PageBreak öğelerinin her biri sayfa sayacını ilerletir ve boş sayfalar üretir. Sondaki bir tanesi, pageCount içinde son bir boş sayfa bırakır.
• Birlikte tutma yalnızca eşleştirilmiş her iki öğe de tek bir sayfaya birlikte sığdığında geçerlidir. Birleşik yüksekliği tam bir sayfayı aşan bir çift yine de bölünür.
• Pozitif olmayan bir widthPt, bölge genişliğine çözülür; ikame denetimi tam olarak sıfırdan büyüktür.
• İmleç taştıktan sonra remainingHeight() sıfır veya negatif bir değer döndürebilir. contains(), bölge sınırını içeride sayar.
• Aralık dışı bir dizinle çağrılan placementsOnPage() boş bir liste döndürür.
• Bu modül hiçbir kriptografik işlem gerçekleştirmez ve FIPS’e özgü hiçbir davranış tanımlamaz.

Uygunluk

Flow Layout, NextPDF tarafından tanımlanan yerleştirme davranışını uygular. Harici bir yerleşim veya tipografi standardını hedeflemez, bu nedenle bu sayfa normatif bir atıf tablosu taşımaz. Sayfa sonu stratejileri NextPDF anlamlarıdır; CSS fragmentasyon özelliklerinin veya herhangi bir XSL-FO keep modelinin uygulamaları değildir. Tüm boyutlar, Core yazıcısının tükettiği birimlerle eşleşerek puan cinsinden ifade edilir.

Bu ifadeler yalnızca yeteneği tanımlar. NextPDF hiçbir uygunluk sertifikasına sahip değildir ve hiçbir sertifika iddiası yapılmaz veya ima edilmez.

Geliştirme notları

• İçeriği önceden ölçün. Motor, çağıran tarafından sağlanan yükseklikleri tüketir; hiçbir font metriği yoktur ve hiçbir metin ölçümü gerçekleştirmez.
• Uzun metin veya tablo içeriğini yerleştirmeden önce birden çok öğeye önceden bölün. Bir parçalayıcının hangi türleri bölebileceğine karar vermek için isBreakable() kullanın.
• Sayfa geometrisi başına tek bir motoru yeniden kullanın. withStrategy() ve withRegion() ile varyantları ucuza türetin.
• Sayfa sayfa işlerken çıktıyı sayfa başına placementsOnPage() ile gruplayın.
• Yerleşim tek bir geçiştir, öğe sayısında doğrusaldır ve hiçbir belge ağacı tutmaz. Sonuçlar belirlenimcidir, bu da golden-file testlerine uygundur.
• HTML’den PDF’e işleme için bunun yerine Core HTML işlem hattını kullanın; bu modül bir HTML veya CSS motoru değildir.

Yayımlama sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilir davranışı ve desteklenen genel API yüzeyini belgeler. Dahili ad alanı yolları, yardımcı sınıflar, mekanizma tabloları, runbook dosya adları ve bilet önekleri kapsam dışıdır.

Ayrıca bkz.

• Flow Layout — yetenek genel bakışı
• Document — Derinlemesine başvuru
• Core HTML modülü