تخطيط بوضع الاحتفاظ لشبكة CSS (grid-template-areas)

لمحة سريعة

معاينة اختيارية. وضع الاحتفاظ مُعطَّل افتراضيًا. والوضع الافتراضي Streaming متطابق بايتًا ببايت مع بناء لم يعرف قطّ بوجود هذا الوضع. فعِّله فقط للمستندات التي تحتاج إلى شبكة حقيقية، وتحقّق من النتيجة.

افتراضيًا، المُصيِّر أحادي المرور وتدفّقي (راجع ADR-001). لا يمكن وضع شبكة ⁨CSS⁩ مُعلَنة بـ grid-template-areas في مرور أمامي واحد، فيُصدر المحرّك التدفّقي تحذير HTML_GRID_REQUIRES_RETAINED ويرتدّ إلى التدفّق الكتليّ. ووضع الاحتفاظ هو الخيار الاختياري الذي يستبدل بذلك الارتداد تخطيطًا حقيقيًا: Config::withCssLayoutMode(CssLayoutMode::Retained) يوجّه شبكة grid-template-areas ذات الأعمدة المحدّدة عبر GridLayoutEngine، الذي يضع الأبناء في خلاياهم المُسمّاة.

التثبيت

composer require nextpdf/core:^3

يُشحَن وضع التخطيط في حزمة core. الخيار الاختياري Config::withCssLayoutMode هو @since 6.0.0. ويبقى الافتراضي CssLayoutMode::Streaming.

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

CssLayoutMode تعداد مُحدَّد النوع على Config. والوضع Streaming هو الافتراضي والسلوك التاريخي؛ بينما Retained يُدخِل المستند في محرّك الشبكة. يحتفظ وضع الاحتفاظ بمجموعة عُقَد محتفَظ بها محدودة (الـ retainedNodeBudget، الافتراضي 50,000، مُقيَّد إلى [5,000, 100,000]) ليتمكّن المحرّك من حلّ شبكة لا يستطيع التدفّق حلّها — دون التخلّي عن انضباط ذاكرة المحرّك.

عندما يكون وضع الاحتفاظ مُفعَّلًا ويلتقي المحرّك بشبكة grid-template-areas أعمدتها محدّدة، يُخطّطها فعليًا. والأعمدة المحدّدة هي أطوال ثابتة، أو نِسَب مئوية، أو وحدات fr مُحلَّلة مقابل عرض المحتوى. وتتدفّق الصفوف تلقائيًا. ويُسنَد الأبناء إلى الخلايا التي تنتقيها أسماء مناطقهم.

يُسجِّل ADR-001 ثابت التدفّق. ويُضيف تعديل 2026-06-28 على ADR-001 استثناءً اختياريًا للاحتفاظ: يبقى الافتراضي التدفّقي دون مساس ويظلّ النموذج أحادي المرور؛ ويُعدّ وضع الاحتفاظ استثناءً اختياريًا محدودًا صراحةً لحالة الشبكة.

الحدّ — ما يُخطّطه وضع الاحتفاظ، وما يبقى يرتدّ

يُعالج وضع الاحتفاظ حالة grid-template-areas ذات الأعمدة المحدّدة وتلك الحالة فقط. وكل ما عداها يُبقي تحذير HTML_GRID_REQUIRES_RETAINED والارتداد الكتليّ، حتى مع تفعيل وضع الاحتفاظ:

• grid-auto-flow: column وgrid-auto-flow: dense.
• subgrid.
• استعلامات @container.
• مسارات أعمدة تلقائية أو جوهرية (auto، min-content، max-content).

هذه شرائح مؤجَّلة، لا فجوات صامتة. أي شبكة تعتمد على إحداها تتدهور إلى التدفّق الكتليّ وتُخبرك بذلك.

حدّ الإغلاق الآمن. أي عدم تطابق بين العرض المُلتقَط والمحرّك — اختلاف عرض المحتوى المُقاس عن العرض الذي يحلّ محرّك الشبكة مقابله — يُغلَق بأمان بدلًا من إنتاج شبكة في غير موضعها. ووضع الاحتفاظ غير متوافق أيضًا مع وضع تصيير ⁨CSS⁩ الآمن: اقتران CssRenderingMode::Safe مع CssLayoutMode::Retained يطرح IncompatibleRenderingModeException عند التحقّق من التهيئة. وCssLayoutMode::Auto محجوز ويطرح NotImplementedException.

سطح الـ ⁨API⁩

الرمز	الموقع	الدور
Config::withCssLayoutMode(CssLayoutMode $mode): self	src/Core/Config.php	يُدخِل المستند في تخطيط Streaming (الافتراضي) أو Retained.
Config::withRetainedNodeBudget(int $budget): self	src/Core/Config.php	يحدّ مجموعة العُقَد المحتفَظ بها ([5,000, 100,000]، الافتراضي 50,000).
Config::isRetainedMode(): bool	src/Core/Config.php	يُبلِغ عمّا إذا كان المستند في وضع الاحتفاظ.
CssLayoutMode	src/Core/	Streaming، Retained؛ وAuto محجوز (NotImplementedException).
GridLayoutEngine	src/Html/	محرّك وضع الشبكة بالاحتفاظ.
IncompatibleRenderingModeException	src/Exception/	يُطرَح عند اقتران وضع CSS الآمن مع وضع الاحتفاظ.

نموذج برمجي — بداية سريعة

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\CssLayoutMode;
use NextPDF\Core\Document;

$config = (new Config())->withCssLayoutMode(CssLayoutMode::Retained);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<style>'
    . '.dashboard { display: grid; grid-template-columns: 1fr 2fr;'
    . '  grid-template-areas: "sidebar main"; }'
    . '.sidebar { grid-area: sidebar; } .main { grid-area: main; }'
    . '</style>'
    . '<div class="dashboard">'
    . '  <div class="sidebar">Navigation</div>'
    . '  <div class="main">Report content…</div>'
    . '</div>',
);
$doc->save(__DIR__ . '/grid.pdf');

نموذج برمجي — إنتاجي

اكتشف حالة الوضع غير المتوافق وقت التهيئة، واقرأ الوضع النشط مرّةً أخرى ليكون المسار صريحًا.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\CssLayoutMode;
use NextPDF\Core\Document;
use NextPDF\Exception\IncompatibleRenderingModeException;

try {
    $config = (new Config())
        ->withCssLayoutMode(CssLayoutMode::Retained)
        ->withRetainedNodeBudget(75_000);
    $config->validate();
} catch (IncompatibleRenderingModeException $e) {
    // Safe CSS mode and retained mode cannot combine. Choose one.
    throw $e;
}

$doc = Document::createStandalone($config);
assert($config->isRetainedMode());

$doc->addPage();
$doc->writeHtml($gridHtml);
$doc->save($out);

// A grid that needs a deferred feature (column auto-flow, subgrid, @container,
// or intrinsic columns) still emits HTML_GRID_REQUIRES_RETAINED and falls back
// to block flow. Inspect the advisory channel.

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

• يبقى Streaming الافتراضي ومتطابقًا بايتًا ببايت. يُغيِّر وضع الاحتفاظ المُخرجات فقط للمستند الذي تختاره.
• فقط grid-template-areas ذات الأعمدة المحدّدة. تدفّق الأعمدة التلقائي، والحزم الكثيف، وsubgrid، و@container، والأعمدة الجوهرية تُبقي تحذير HTML_GRID_REQUIRES_RETAINED والارتداد الكتليّ.
• الوضع الآمن متبادِل الاستبعاد. CssRenderingMode::Safe مع CssLayoutMode::Retained يطرح IncompatibleRenderingModeException.
• Auto محجوز. CssLayoutMode::Auto يطرح NotImplementedException؛ وهو ليس خيارًا ثالثًا قابلًا للاستخدام بعد.
• عدم تطابق العرض يُغلَق بأمان. أي اختلاف في عرض المحتوى بين الالتقاط والمحرّك يُرفَض، لا يُصيَّر خطأً.

الأداء

يحتفظ وضع الاحتفاظ بمجموعة عُقَد محدودة بدلًا من شجرة مستند كاملة؛ ويحدّها الـ retainedNodeBudget (الافتراضي 50,000). ووضع الشبكة خطّيٌّ في عدد العُقَد والخلايا. وتنطبق ميزانية الأداء performance_budget لكل صفحة (wall_ms: 1500، peak_mb: 64)؛ وينبغي للشبكات الكبيرة مراعاة الميزانية عند رفع ميزانية العُقَد نحو سقفها البالغ 100,000.

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

لا يُوسِّع وضع الاحتفاظ سطح المُدخلات. تنطبق سياسة أمان ⁨HTML⁩، وقائمة خصائص ⁨CSS⁩ المسموح بها، وحدود المُحلِّل دون تغيير. وميزانية العُقَد المحتفَظ بها هي نفسها حدّ لاستنزاف الموارد: فهي تحدّ مقدار البنية التي سيحتفظ بها المحرّك لمستند واحد.

المطابقة

العبارة	المواصفة	البند
grid-template-areas يُسمّي خلايا الشبكة؛ والمناطق المُسمّاة تضع العناصر.	W3C CSS Grid Layout Module Level 1	§7.3
تُحدِّد المسارات الثابتة والنِّسبية ووحدات fr الصريحة الحجم مقابل عرض المحتوى.	W3C CSS Grid Layout Module Level 1	§7.2

هذا تطبيق معاينة لمجموعة فرعية من grid-template-areas ذات الأعمدة المحدّدة. ويُتتبَّع الوضع المُتحقَّق منه لكل خاصية في مصفوفة دعم ⁨CSS⁩؛ ولا تُدَّعى أي مطابقة شاملة من طرفٍ إلى طرف هنا. ولا يُعاد إنتاج أي نص معياري.

انظر أيضًا

• نظام تصيير ⁨HTML⁩ الفرعي
• قيود التدفّق أحادي المرور (ADR-001)
• أعلام معاينة ⁨CSS⁩ للوسائط المُصفَّحة
• وحدة Config
• مصفوفة دعم ⁨CSS⁩