⁨Flow Layout⁩ — مرجع متعمّق

لمحة سريعة

هذه الصفحة هي المرجع المتعمّق لوحدة ⁨Flow Layout⁩ في ⁨NextPDF Pro⁩. تغطي محرك التنسيب، ونموذج العنصر، واستراتيجيات فصل الصفحات، وعقود سلوكها، وأنماط إخفاقها. يمشي StreamingLayoutEngine عبر قائمة من قيم FlowElement بالترتيب. يُسنِد لكل قيمة فهرس صفحة يبدأ من صفر وموضعًا داخل LayoutRegion. النتيجة هي LayoutResult من سجلّات PlacedElement غير القابلة للتغيير. الوحدة تحسب التنسيب فقط؛ لا تُصيّر شيئًا ولا تُجري أي إدخال/إخراج.

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

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

لا توجد راية ترخيص لكل ميزة. هذه قدرة من إصدار ⁨Pro⁩.

واجهة ⁨API⁩ العامة

جميع الرموز تقع في فضاء الأسماء NextPDF\Pro\FlowLayout. جميع كائنات القيمة final وغير قابلة للتغيير.

الرمز	المعاملات	السلوك الافتراضي	القيمة المُعادة	يرمي أو يفشل بـ	ملاحظات
StreamingLayoutEngine::__construct	LayoutRegion $region, PageBreakStrategy $strategy = PageBreakStrategy::Greedy	يربط منطقة محتوى لكل صفحة باستراتيجية فصل	StreamingLayoutEngine	—	الاستراتيجية الافتراضية هي Greedy.
StreamingLayoutEngine::layout	list<FlowElement> $elements	تمريرة أمامية واحدة؛ تنسيب متسلسل مع فواصل صفحات تقودها الاستراتيجية	LayoutResult	لا يرمي أبدًا	قائمة فارغة تُنتج صفحة فارغة واحدة.
StreamingLayoutEngine::withStrategy	PageBreakStrategy $strategy	يشتقّ محركًا جديدًا بالمنطقة نفسها	self	—	المُستقبِل يبقى دون تغيير.
StreamingLayoutEngine::withRegion	LayoutRegion $region	يشتقّ محركًا جديدًا بالاستراتيجية نفسها	self	—	المُستقبِل يبقى دون تغيير.
FlowElement::__construct	FlowElementType $type, string $content, float $widthPt = 0, float $heightPt = 0, float $marginTopPt = 0, float $marginBottomPt = 0, bool $keepWithNext = false	كائن قيمة عنصر غير قابل للتغيير	FlowElement	—	مسار الإنشاء الوحيد لعناصر Table.
FlowElement::text	string $content, float $height	عنصر نصّي بارتفاع يقيسه المُستدعي	self (ساكنة)	—	العرض 0 يُحلّ إلى عرض المنطقة عند التنسيب.
FlowElement::image	string $path, float $width, float $height	عنصر صورة؛ الحقل content يحمل المسار	self (ساكنة)	—	المحرك لا يفتح الملف أبدًا.
FlowElement::spacer	float $height	مسافة بيضاء رأسية بمحتوى فارغ	self (ساكنة)	—	—
FlowElement::pageBreak	—	علامة فصل صريحة	self (ساكنة)	—	لا يُصدر أي PlacedElement.
FlowElement::totalHeight	—	الارتفاع زائد الهامشين العلوي والسفلي	float	—	جميع فحوص الملاءمة تستخدم هذه القيمة.
FlowElementType	حالات التعداد Text, Image, Table, Spacer, PageBreak	مدعوم بسلسلة: text, image, table, spacer, page_break	—	—	—
FlowElementType::isBreakable	—	Text وTable تُعيدان true؛ والبقية تُعيد false	bool	—	تصنيف فقط؛ انظر عقد التنسيب الذرّي أدناه.
LayoutRegion::__construct	float $x, float $y, float $width, float $height	صندوق محتوى بأصل أعلى-اليسار، مُقاس بالنقاط	LayoutRegion	—	لا تحقّق؛ تُؤخذ القيم كما هي.
LayoutRegion::contains	float $px, float $py	اختبار وقوع نقطة داخل المنطقة شامل للحدود	bool	—	—
LayoutRegion::remainingHeight	float $currentY	ارتفاع المنطقة ناقص الإزاحة الرأسية المستهلكة	float	—	صفر أو سالب بمجرّد أن يتجاوز المؤشر الحدّ.
LayoutResult::__construct	list<PlacedElement> $placements, int $pageCount, float $totalHeightPt	نتيجة تخطيط غير قابلة للتغيير	LayoutResult	—	—
LayoutResult::placementsOnPage	int $pageIndex	يُرشّح التنسيبات حسب فهرس صفحة يبدأ من صفر	list<PlacedElement>	—	القائمة المُعادة يُعاد فهرستها.
LayoutResult::isEmpty	—	true عندما لا يُنسَّب أي عنصر	bool	—	true للمُدخل الفارغ وللمُدخل المكوَّن من فواصل فقط.
PageBreakStrategy	حالات التعداد Greedy, AvoidOrphans, KeepTogether	مدعوم بسلسلة: greedy, avoid_orphans, keep_together	—	—	—
PageBreakStrategy::label	—	تسمية استراتيجية قابلة للقراءة البشرية	string	—	—
PlacedElement::__construct	FlowElement $element, int $pageIndex, float $x, float $y, float $width, float $height	سجلّ تنسيب غير قابل للتغيير	PlacedElement	—	الإحداثيات بالنقاط، والأصل أعلى-اليسار.

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

عقد السلوك

ينفّذ StreamingLayoutEngine::layout() تمريرة أمامية واحدة على قائمة المُدخل. لكل عنصر يفحص الملاءمة، ويفصل الصفحة عند اللزوم، ثم يسجّل PlacedElement. قائمة مُدخل فارغة تُعيد LayoutResult بلا تنسيبات، وبعدد صفحات يساوي 1، وبارتفاع إجمالي يساوي 0.

هندسة التنسيب حتمية:

• x هو الحافة اليسرى للمنطقة.
• y هو موضع المؤشر الحالي زائد الهامش العلوي للعنصر.
• width هو widthPt للعنصر عندما يكون موجبًا، وإلا فعرض المنطقة.
• height هو heightPt للعنصر، تمامًا كما زُوّد.

بعد كل تنسيب يتقدّم المؤشر بمقدار totalHeight()، بما في ذلك الهوامش. يتراكم المقدار نفسه في LayoutResult::totalHeightPt.

قواعد فصل الصفحات، بترتيب التقييم:

• عنصر PageBreak صريح يزيد فهرس الصفحة ويعيد ضبط المؤشر إلى أعلى المنطقة. لا يُصدر أي تنسيب ولا يضيف شيئًا إلى الارتفاع الإجمالي.
• عندما يتجاوز totalHeight() لعنصرٍ الارتفاعَ المتبقّي، يفصل المحرك — إلا إذا كان المؤشر بالفعل عند أعلى الصفحة.
• Greedy لا يضيف أي شرط إضافي: العناصر المُلائمة تُنسَّب دائمًا.
• AvoidOrphans يفصل قبل عنصر مُلائم عندما تكون المساحة المتبقّية بعد التنسيب موجبة لكنها أقل من نصف الارتفاع المطلوب للعنصر نفسه. ارتفاع العنصر نفسه هو وحدة المرجع، بمقسوم ثابت قدره اثنان؛ ولا يدخل في ذلك أي مقياس خط. ولا يفصل أبدًا عند أعلى الصفحة.
• KeepTogether يفصل قبل عنصر مُلائم عندما تكون رايته keepWithNext مضبوطة، ويوجد عنصر تالٍ، والمؤشر ليس عند أعلى الصفحة، ويتجاوز مجموع totalHeight() للعنصرين المساحة المتبقّية. الراية على العنصر الأخير لا أثر لها.

التنسيب الذرّي: يُنسّب المحرك كل عنصر كوحدة واحدة. ولا يقسم محتوى العنصر عبر الصفحات أبدًا. يصنّف FlowElementType::isBreakable() أيّ الأنواع يجوز للمُستدعي تقسيمها مسبقًا إلى عناصر أصغر؛ والمحرك نفسه لا يستشيرها.

انعدام الحالة والحتمية: لا يحمل المحرك سوى منطقته واستراتيجيته. لا يشارك layout() أي حالة بين الاستدعاءات، والمُدخلات المتطابقة تُنتج نتائج متطابقة. تُعيد withStrategy() وwithRegion() محرّكات جديدة ولا تُغيّران المُستقبِل أبدًا.

الحالات الحدّية وأنماط الإخفاق

• لا ترمي أيّ دالة في هذه الوحدة. ولا يوجد تسلسل استثناءات لالتقاطه.
• البواني لا تتحقّق من شيء. أبعاد منطقة سالبة أو صفرية، وارتفاعات عناصر سالبة، وهوامش سالبة كلها مقبولة وتمرّ عبر الحساب دون تغيير.
• عنصر أطول من المنطقة يُنسَّب مع ذلك. عند أعلى الصفحة يُنسَّب هناك ويتجاوز الحدّ؛ وفي غير ذلك يفصل المحرك أولًا فيتجاوز الحدّ في صفحة جديدة. عندئذٍ يُطلق العنصر التالي فصلًا دائمًا، فيبقى التجاوز محصورًا في صفحة واحدة.
• PageBreak في المقدّمة يُنسّب أول عنصر محتوى على فهرس الصفحة 1، فيصير عدد الصفحات 2 على الأقل.
• عناصر PageBreak المتتالية يُقدّم كلٌّ منها عدّاد الصفحات، فتنتج صفحات فارغة. وواحد في النهاية يترك صفحة فارغة أخيرة في pageCount.
• الإبقاء-معًا يصمد فقط عندما يُلائم العنصران المقترنان صفحة واحدة معًا. زوج يتجاوز ارتفاعه المجموع صفحة كاملة ينقسم مع ذلك.
• widthPt غير الموجب يُحلّ إلى عرض المنطقة؛ وفحص الاستبدال أكبر من صفر تمامًا.
• قد تُعيد remainingHeight() صفرًا أو قيمة سالبة بمجرّد أن يتجاوز المؤشر الحدّ. وتعامل contains() حدَّ المنطقة كأنه داخلها.
• placementsOnPage() بفهرس خارج المدى تُعيد قائمة فارغة.
• هذه الوحدة لا تُجري أي عمليات تشفيرية ولا تُعرّف أي سلوك خاص بـ ⁨FIPS⁩.

المطابقة

يُنفّذ ⁨Flow Layout⁩ سلوك تنسيب مُعرَّفًا من ⁨NextPDF⁩. وهو لا يستهدف أي معيار تخطيط أو طباعة خارجي، لذا لا تحمل هذه الصفحة جدول استشهادات معياريًا. استراتيجيات فصل الصفحات هي دلالات ⁨NextPDF⁩؛ وليست تنفيذات لخصائص تجزئة ⁨CSS⁩ ولا لأي نموذج إبقاء من ⁨XSL-FO⁩. جميع الأبعاد مُعبَّر عنها بالنقاط، بما يطابق الوحدات التي يستهلكها كاتب ⁨Core⁩.

تصف هذه العبارات القدرة فقط. لا تحمل ⁨NextPDF⁩ أي شهادة مطابقة، ولا يُقدَّم أو يُلمَّح إلى أي ادعاء شهادة.

ملاحظات التطوير

• قِس المحتوى في المنبع. يستهلك المحرك ارتفاعات يزوّدها المُستدعي؛ فليست لديه مقاييس خطوط ولا يُجري أي قياس نصّي.
• قسّم مسبقًا النص الطويل أو محتوى الجداول إلى عناصر متعددة قبل التخطيط. استخدم isBreakable() لتقرير أيّ الأنواع يجوز لمُجزّئ أن يقسمها.
• أعِد استخدام محرك واحد لكل هندسة صفحة. اشتقّ المتغايرات بتكلفة زهيدة عبر withStrategy() وwithRegion().
• جمّع المُخرَج لكل صفحة عبر placementsOnPage() عند التصيير صفحةً صفحة.
• التخطيط تمريرة واحدة، خطّي في عدد العناصر، ولا يحتفظ بأي شجرة مستند. النتائج حتمية، وهو ما يناسب اختبارات الملفات الذهبية.
• لتصيير ⁨HTML⁩ إلى ⁨PDF⁩، استخدم خط أنابيب ⁨HTML⁩ في ⁨Core⁩ بدلًا من ذلك؛ فهذه الوحدة ليست محرك ⁨HTML⁩ أو ⁨CSS⁩.

حدود النشر

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

انظر أيضًا

• ⁨Flow Layout⁩ — نظرة عامة على القدرة
• ⁨Document⁩ — المرجع المتعمّق
• وحدة ⁨HTML⁩ في ⁨Core⁩