Flow Layout

Bir bakışta

NextPDF Pro, bir akış öğeleri dizisini — metin, görüntü, tablo, ara çubuğu — sayfalara yerleştirir ve her birine somut bir sayfa ve konum atar. Sayfa sonu davranışı seçilebilir: açgözlü, yetim önleyici veya birlikte tutan.

Kullanılabilirlik ve lisanslama

Bu yetenek NextPDF Pro (nextpdf/pro) ile birlikte gelir ve Pro katmanı bir lisans zarfıyla etkinleşir. Bu yetkilendirmeye sahip olmayan bir dağıtım, yeteneğin sınıflarını yüklemez. Ayrı bir özellik başına lisans bayrağı yoktur; Pro zarfı bunu etkinleştirir. Sürümleri karşılaştırın ve bir lisans edinin.

Kurulum

composer require nextpdf/pro:^3

Kavramsal genel bakış

Akış yerleşim motoru, bir akış öğeleri listesi ile bir içerik bölgesi alır, ardından öğeleri sırayla dolaşır ve her birine bir sayfa ve konum atar. Bir öğe kalan dikey alana sığmadığında, motor yapılandırılan stratejiye göre yeni bir sayfa başlatır:

• StreamingLayoutEngine — motor. Bir LayoutRegion (sayfa başına içerik alanı) ve bir PageBreakStrategy ile oluşturulur. Yerleştirilen öğelerden oluşan bir LayoutResult döndürür.
• FlowElement / FlowElementType — öğe modeli. Metin ve tablolar sayfalar boyunca bölünebilir; motor, görüntüleri ve ara çubuklarını bölünmez biçimde yerleştirir.
• PageBreakStrategy — üç davranışa sahip bir enum:
  • Greedy — bir sonraki öğe sığmaz sığmaz böl.
  • AvoidOrphans — yeni bir sayfanın üstünde tek bir öğe bırakmamak için, yalnızca az bir alan kaldığında erken böl.
  • KeepTogether — eşleştirilen öğelerin mümkün olduğunda aynı sayfada kalması için sonrakiyle-birlikte-tut bayrağını gözet.

Flow Layout, bir öğe yerleştirme motorudur. Sayfa ve konum atamalarını hesaplar; bir HTML veya CSS işleme motoru değildir. HTML’den PDF’e için Core HTML işlem hattını kullanın.

Neden bu şekilde çalışır

Motor, her öğeye tek bir ileri geçişte bir sayfa ve konum atar. Daha sonra yeniden akıtmak için asla tam bir belge ağacını arabelleğe almaz. Bu, belge ne kadar uzun sürerse sürsün belleği sınırlı tutar ve maliyeti öğe sayısında doğrusal yapar. Her sayfa sonu kararı, geçerli imleç ve seçilen strateji üzerinde yerel bir yüklemdir. Böylece açgözlü, yetim önleme ve birlikte tutma davranışlarının hepsi aynı akış geçişi içinde çözülür. Ödün, ileriye dönük bağlanmadır: aşırı uzun bir öğe yeniden ölçeklenmek yerine taşar ve birlikte tutma yalnızca eşleştirilen her iki öğe de aynı sayfayı paylaştığında geçerlidir.

Tasarım arka planı: Yüksek hacimli belge oluşturma.

API yüzeyi

Sınıf	Sorumluluk
StreamingLayoutEngine	Akış öğelerine sayfa ve konum atar.
FlowElement, FlowElementType	Öğe modeli ve tür enum’u.
LayoutRegion	Sayfa başına içerik alanı.
PageBreakStrategy	Sayfa sonu davranışı enum’u.
LayoutResult, PlacedElement	Yerleştirme çıktısı.

Kod örneği — Hızlı başlangıç

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

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

Kod örneği — Üretim

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

Uç durumlar ve dikkat edilmesi gerekenler

• Motor, bölgeden daha uzun bir öğeyi yine de yerleştirir, ancak taşma olabilir; öğeleri bölge yüksekliği içinde boyutlandırın.
• KeepTogether, çiftleri yalnızca her ikisi de tek bir sayfaya sığdığında birlikte tutar.
• AvoidOrphans, bölmeden önce en az iki öğe yüksekliği ayırır.

Performans

Yerleşim, öğe sayısında doğrusaldır. Motor akış tabanlıdır: tam bir belge ağacını tutmaz.

Güvenlik notları

Flow Layout, sağladığınız öğe meta verisi üzerinde çalışır. Hiçbir giriş/çıkış gerçekleştirmez.

Uygunluk

Flow Layout, NextPDF yerleştirme davranışını uygular; harici bir yerleşim standardını hedeflemez.

Davranış sözleşmesi

• StreamingLayoutEngine, bir LayoutRegion ve bir PageBreakStrategy ile oluşturulur ve somut sayfa ve konum atamalarıyla yerleştirilen öğelerden oluşan bir LayoutResult döndürür.
• PageBreakStrategy, üç davranışa sahiptir: Greedy (bir sonraki öğe sığmadığında böl), AvoidOrphans (en az iki öğe yüksekliği ayırarak erken böl) ve KeepTogether (her ikisi de sığdığında eşleştirilen öğelerin tek sayfada kalması için sonrakiyle-birlikte-tut bayrağını gözet).
• Metin ve tablolar sayfalar boyunca bölünebilir; görüntüler ve ara çubukları bölünmez biçimde yerleştirilir. Bölgeden daha uzun bir öğe yine de yerleştirilir ancak taşabilir.
• Motor akış tabanlıdır: tam bir belge ağacını tutmaz ve hiçbir giriş/çıkış gerçekleştirmez.
• Bu, bir öğe yerleştirme motorudur. Sayfa ve konum atamalarını hesaplar; bir HTML veya CSS işleme motoru değildir.

Enterprise sınır notu

Enterprise, Flow Layout davranışını değiştirmez. Enterprise, ayrı olarak belgelenen üst katman özellikleri ekler; bunlar yerleştirme motorunu kullanmak için gerekli değildir.

Core geri dönüşü / alternatifi

Sayfa sonu stratejilerine sahip hiçbir Core öğe yerleştirme motoru yoktur. HTML’den PDF’e işleme için açık kaynaklı Core HTML işlem hattını kullanın. Bkz. /modules/html/.

Yayın sınırı

Bu sayfa yalnızca dışarıdan gözlemlenebilen davranışı ve desteklenen genel API yüzeyini belgeler. İç 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 — Derinlemesine başvuru — tam sınıf ve yöntem başvurusu.
• Document — belge oluşturma.
• Core HTML modülü — HTML’den PDF’e işleme.