تخطيط التدفّق

لمحة سريعة

يضع ⁨NextPDF Pro⁩ تتابعًا من عناصر التدفّق — نص، صور، جداول، فواصل — على الصفحات، مُسنِدًا كلًّا منها صفحةً وموضعًا محدّدين. سلوك فاصل الصفحات قابل للاختيار: جشِع، أو متجنّب لليتيم، أو مُبقٍ على التجميع.

التوفّر والترخيص

تتوفّر هذه القدرة في ⁨NextPDF Pro⁩ (nextpdf/pro) وتُفعَّل مع مظروف ترخيص من طبقة ⁨Pro⁩. النشر الذي لا يملك ذلك الاستحقاق لا يُحمِّل أصناف القدرة. لا يوجد علم ترخيص منفصل لكل ميزة؛ مظروف ⁨Pro⁩ هو ما يُمكّنها. ‏قارن الإصدارات واحصل على ترخيص.

التثبيت

composer require nextpdf/pro:^3

نظرة مفاهيمية عامة

يأخذ محرّك التخطيط المتدفّق قائمة من عناصر التدفّق ومنطقة محتوى، ثم يجوب العناصر بالترتيب ويُسنِد كلًّا منها صفحةً وموضعًا. عندما لا يلائم عنصرٌ المساحة العمودية المتبقية، يبدأ المحرّك صفحة جديدة وفق الاستراتيجية المُهيّأة:

• StreamingLayoutEngine — المحرّك. يُنشأ بـ LayoutRegion (منطقة المحتوى لكل صفحة) وPageBreakStrategy. يُعيد LayoutResult من العناصر الموضوعة.
• FlowElement / FlowElementType — نموذج العنصر. يمكن أن ينكسر النص والجداول عبر الصفحات؛ ويضع المحرّك الصور والفواصل وضعًا ذرّيًا.
• PageBreakStrategy — تعداد بثلاثة سلوكيات:
  • Greedy — اكسِر بمجرّد ألّا يلائم العنصر التالي.
  • AvoidOrphans — اكسِر مبكرًا عندما يتبقّى قدر صغير فقط من المساحة، لتجنّب ترك عنصر مفرد أعلى صفحة جديدة.
  • KeepTogether — احترِم علم الإبقاء-مع-التالي لكي تبقى العناصر المُقترِنة على الصفحة نفسها متى أمكن.

‏⁨Flow Layout⁩ محرّك وضع عناصر. يحسب إسنادات الصفحة والموضع؛ وهو ليس محرّك عرض ⁨HTML⁩ أو ⁨CSS⁩. لأجل ⁨HTML⁩ إلى ⁨PDF⁩، استخدم مسار ⁨HTML⁩ في ⁨Core⁩.

لماذا يعمل بهذه الطريقة

يُسنِد المحرّك كلَّ عنصر صفحةً وموضعًا في تمريرة أمامية واحدة. ولا يخزّن مطلقًا شجرة مستند كاملة لإعادة التدفّق لاحقًا. وهذا يُبقي الذاكرة محدودة مهما طال المستند، ويجعل التكلفة خطّية بعدد العناصر. كل قرار فاصل صفحات هو مسند محلي على المؤشّر الحالي والاستراتيجية المختارة. لذا تُحسم كلٌّ من الجشِعة وتجنّب اليتيم والإبقاء-معًا ضمن الجولة المتدفّقة نفسها. المقايضة هي الالتزام الأمامي: العنصر المفرط الطول يفيض بدلًا من إعادة القياس، والإبقاء-معًا يصمد فقط عندما يتشارك العنصران المُقترِنان صفحة واحدة.

خلفية التصميم: توليد المستندات عالي الحجم.

سطح الـ ⁨API⁩

الصنف	المسؤولية
StreamingLayoutEngine	إسناد الصفحات والمواضع إلى عناصر التدفّق.
FlowElement, FlowElementType	نموذج العنصر وتعداد النوع.
LayoutRegion	منطقة المحتوى لكل صفحة.
PageBreakStrategy	تعداد سلوك فاصل الصفحات.
LayoutResult, PlacedElement	مخرَج الوضع.

مثال شيفرة — بداية سريعة

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

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

مثال شيفرة — إنتاج

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

الحالات الحدّية والمزالق

• يضع المحرّك مع ذلك عنصرًا أطول من المنطقة، لكنه قد يفيض؛ حدّد حجم العناصر ضمن ارتفاع المنطقة.
• يُبقي KeepTogether الأزواج معًا فقط عندما يلائم كلاهما صفحة واحدة.
• يحجز AvoidOrphans ارتفاعَي عنصرين على الأقل قبل الكسر.

الأداء

التخطيط خطّي بعدد العناصر. المحرّك متدفّق: لا يحتفظ بشجرة مستند كاملة.

ملاحظات أمنية

يعمل ⁨Flow Layout⁩ على بيانات العنصر الوصفية التي تزوّدها. ولا يُجري أي إدخال/إخراج.

المطابقة

ينفّذ ⁨Flow Layout⁩ سلوك الوضع الخاص بـ ⁨NextPDF⁩؛ وهو لا يستهدف معيار تخطيط خارجيًا.

عقد السلوك

• يُنشأ StreamingLayoutEngine بـ LayoutRegion وPageBreakStrategy ويُعيد LayoutResult من العناصر الموضوعة بإسنادات صفحة وموضع محدّدة.
• لـ PageBreakStrategy ثلاثة سلوكيات: Greedy (اكسِر عندما لا يلائم العنصر التالي)، وAvoidOrphans (اكسِر مبكرًا، حاجزًا ارتفاعَي عنصرين على الأقل)، وKeepTogether (احترِم الإبقاء-مع-التالي لكي تبقى العناصر المُقترِنة على صفحة واحدة عندما يلائم كلاهما).
• يمكن أن ينكسر النص والجداول عبر الصفحات؛ وتُوضَع الصور والفواصل وضعًا ذرّيًا. العنصر الأطول من المنطقة يُوضَع مع ذلك لكنه قد يفيض.
• المحرّك متدفّق: لا يحتفظ بشجرة مستند كاملة ولا يُجري أي إدخال/إخراج.
• هذا محرّك وضع عناصر. يحسب إسنادات الصفحة والموضع؛ وهو ليس محرّك عرض ⁨HTML⁩ أو ⁨CSS⁩.

ملاحظة حدود ⁨Enterprise⁩

لا يغيّر ⁨Enterprise⁩ سلوك ⁨Flow Layout⁩. يضيف ⁨Enterprise⁩ ميزات من طبقة أعلى موثَّقة بشكل منفصل؛ وهي ليست مطلوبة لاستخدام محرّك الوضع.

احتياط ⁨Core⁩ / بديله

لا يوجد محرّك وضع عناصر في ⁨Core⁩ باستراتيجيات فاصل صفحات. لأجل عرض ⁨HTML⁩ إلى ⁨PDF⁩، استخدم مسار ⁨HTML⁩ مفتوح المصدر في ⁨Core⁩. انظر /modules/html/.

حدود النشر

تُوثّق هذه الصفحة السلوك القابل للملاحظة خارجيًا وسطح ⁨API⁩ العام المدعوم فقط. مسارات مجالات الأسماء الداخلية، والأصناف المساعدة، وجداول الآليات، وأسماء ملفات أدلة التشغيل، وبادئات التذاكر خارج النطاق.

انظر أيضًا

• ⁨Flow Layout⁩ — مرجع متعمّق — مرجع كامل للأصناف والدوال.
• ⁨Document⁩ — تجميع المستند.
• وحدة ⁨HTML⁩ في ⁨Core⁩ — عرض ⁨HTML⁩ إلى ⁨PDF⁩.