الاستقرار: تجريبي

أعلام معاينة CSS للوسائط المُصفَّحة (محتوى GCPM المتكرّر، والصفحات المُسمّاة، وعائمات الصفحة)

لمحة سريعة

معاينة اختيارية. هذه الميزات الأربع في ⁨CSS⁩ مُعطَّلة افتراضيًا. عندما يكون العَلَم مُعطَّلًا، يُنتج المحرّك مُخرجات متطابقة بايتًا ببايت مع بناء لم يعرف قطّ بوجود الميزة. فعِّل ميزةً ما فقط عند رغبتك فيها، وتحقّق من النتيجة لمستنداتك.

يضيف مُصيِّر ⁨HTML⁩ أربع ميزات اختيارية للوسائط المُصفَّحة من وحدتَي ⁨CSS⁩ Paged Media وGenerated Content for Paged Media (GCPM). كلٌّ منها عَلَم منفصل على CssFeatureFlags. ويحمل كلٌّ منها حدًّا صادقًا بالإغلاق الآمن: أي بنية لا يستطيع المحرّك أحادي المرور حلّها بأمانة تُسقَط أو تتدهور مع تشخيص مُسمّى، ولا تُصيَّر خطأً أبدًا.

الميزة	العَلَم	ما تفعله عند التفعيل
السلاسل المُسمّاة (GCPM)	`runningStrings`	التقاط `string-set` بالإضافة إلى `string()` في صناديق هوامش `@page` — رؤوس وتذييلات متكرّرة.
الصفحات المُسمّاة (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`، والخاصية `page:`، و`:first` / `:left` / `:right` / `:blank` — صناديق هوامش وزخرفة لكل صفحة.
العناصر المتكرّرة (GCPM)	`runningElements`	`position: running(<ident>)` بالإضافة إلى `content: element(<ident>)` — إعادة عرض نص عنصرٍ ما في صندوق هامش.
عائمات الصفحة (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — نقل صندوقٍ إلى الشريط العلوي أو السفلي للصفحة.

التثبيت

composer require nextpdf/core:^3

تُشحَن الأعلام في حزمة core. السطح العام CssFeatureFlags هو @since 6.1.0. ونسخة المحرّك (Version::VERSION) لم تتغيّر؛ فهذه الميزات إضافية ومُعطَّلة افتراضيًا.

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

المُصيِّر أحادي المرور وتدفّقي (راجع ADR-001). لا يحتفظ بشجرة مستند ويكتب المُخرجات مرّةً واحدة بترتيب المستند. ويُشكّل ذلك القيد كل ميزة هنا. تحلّ كل ميزة ما يمكنها رؤيته في مرور أمامي واحد وتُغلق بأمان على أي شيء يتطلّب مرورًا ثانيًا أو شجرةً محتفَظًا بها. الحدّ مُوثَّق، لا مُخفًى — فمعرفة أين تتوقّف الميزة جزءٌ من استخدامها.

تُفعِّل ميزةً ما ببناء CssFeatureFlags مع ضبط العَلَم على true وتمريره إلى Config. وعندما يكون العَلَم مُعطَّلًا، يُحلَّل ما يقابله من ⁨CSS⁩ ويُتجاهَل تمامًا كما تُتجاهَل خاصية غير مدعومة، فتكون المُخرجات متطابقة بايتًا ببايت مع بناء بدون الميزة.

السلاسل المُسمّاة — `runningStrings`

يُسجِّل string-set: <ident> content() قيمةً عند مرور المحرّك على العنصر. ثم يُحلّ مرجع string(<ident>) داخل صندوق هامش @page إلى أحدث قيمة شُوهدت على تلك الصفحة. هذه هي الآلية القياسية لرأس متكرّر يتتبّع الفصل أو القسم الحالي.

الحلّ أحادي المرور بمنهج “آخر ما شوهد على هذه الصفحة”. يُحلّ مرجع string() إلى آخر قيمة سجّلها المحرّك قبل أن يُخطّط صناديق هوامش تلك الصفحة.

حدّ الإغلاق الآمن. عند إيقاف العَلَم، يُحلّ string() إلى السلسلة الفارغة وتبقى المُخرجات متطابقة بايتًا ببايت. وقائمة محتوى string-set مُشوّهة تُسقِط ذلك الزوج الواحد من الإسناد وتتابع؛ ولا تُجهِض التصيير أبدًا.

الصفحات المُسمّاة — `namedPagesAdvanced`

تُسنِد الخاصية page: <ident> عنصرًا إلى سياق صفحة مُسمّاة، وتُوفِّر قاعدة @page <ident> المطابِقة صناديق هوامش ذلك السياق وزخرفة الصفحة. وتنتقي الأصناف الزائفة للصفحة :first و:left و:right و :blank الصفحة الأولى، وصفحات الأمام والخلف، والصفحات الفارغة المقصودة.

تنتقي هذه الميزة صناديق هوامش وزخرفة صفحة مُسمّاة أو زائفة. ولا تُغيِّر هندسة الصفحة.

حدّ الإغلاق الآمن. أي قاعدة @page مُسمّاة أو زائفة تحاول تغيير الهندسة — size أو rotate أو هامش صندوق محتوى يُغيِّر مساحة منطقة الصفحة — تُغلَق بأمان مع UnsupportedNamedPageException بدلًا من إنتاج صفحة غير محاذية بصمت. وقناة مطابقة الصنف الزائف هي الشريحة الأولى؛ أما حالات المُنتقِيات الأوسع فمؤجَّلة ومُوثَّقة.

العناصر المتكرّرة — `runningElements`

يُزيل position: running(<ident>) عنصرًا من التدفّق العادي ويُوقِفه تحت اسم. ثم يُعيد content: element(<ident>) في صندوق هامش عرض ذلك العنصر على كل صفحة. استخدمه عندما يحتاج الرأس إلى النص المُنسَّق الكامل لعنوانٍ ما، لا مجرّد سلسلة مُلتقَطة.

حدّ الإغلاق الآمن. تُعيد هذه الشريحة عرض نص العنصر المتكرّر فقط. أما المحتوى الغنيّ — الصور، والعناصر المُستبدَلة، والبنية الكتليّة المتداخلة — فيُسقَط، ويُصدر المحرّك تشخيص HTML_RUNNING_ELEMENT_DEGRADED لتكون الخسارة مرئيةً لا صامتة. وأي عنصر running() يُشير إلى نفسه، أو running() متداخلة، أو التقاط يتجاوز الميزانية الداخلية، يُغلَق بأمان. وعند إيقاف العَلَم، يكون running() وelement() خاملَين.

عائمات الصفحة — `pageFloats`

تنقل float: top وfloat: bottom وfloat: snap صندوقًا إلى الشريط العلوي أو السفلي للصفحة في المحور الكتليّ، مُحجِزةً ارتفاع الشريط بحيث يُعاد تدفّق النص المحيط حول المنطقة المحجوزة.

float: bottom (وsnap المحلولة إلى الشريط السفلي) هي الحالة التي يُعالجها المحرّك أحادي المرور مباشرةً: يُلتقَط الصندوق ويُوضَع في الشريط السفلي للصفحة عند إغلاق الصفحة. وتتدهور float: top إلى شريط أعلى الصفحة.

حدّ الإغلاق الآمن. snap في المحور المُضمَّن (snap-inline) غير مدعومة. وأي صندوق يحمل أثرًا جانبيًا غير قابل للنقل — مثل تعليق رابط، يرتبط مستطيله بموضعه في التدفّق — لا يمكن نقله بأمان، فيرتدّ إلى التدفّق العادي ويُصدر المحرّك تشخيص HTML_PAGE_FLOAT_* يشرح الارتداد. وعند إيقاف العَلَم، تُعامَل float: top | bottom | snap كقيمة غير مدعومة وتُتجاهَل.

سطح الـ ⁨API⁩

الرمز	الموقع	الدور
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	مجموعة أعلام اختيارية غير قابلة للتغيير؛ يأخذ المُنشئ `runningStrings` و`namedPagesAdvanced` و`runningElements` و`pageFloats` (كلها `false` افتراضيًا).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	يُرفِق مجموعة الأعلام بتهيئة المستند.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	يحلّ مجموعة أعلام لوضع تصيير (الوضع Safe يُجبر كل عَلَم على الإيقاف؛ والوضع Normal يستخدم المجموعة الصريحة، أو `allEnabled()` عند عدم توفير أيٍّ منها).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	يُطرَح عندما تُغيِّر قاعدة `@page` مُسمّاة/زائفة هندسة الصفحة.

تظهر رموز التحذير التشخيصية عبر قناة الإرشاد في نتيجة التصيير: HTML_RUNNING_ELEMENT_DEGRADED، وعائلة HTML_RUNNING_ELEMENT_*، وعائلة HTML_PAGE_FLOAT_*.

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

فعِّل السلاسل المُسمّاة لرأس متكرّر يتتبّع الفصل الحالي.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(runningStrings: true),
);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<style>'
    . 'h2 { string-set: chapter content(); }'
    . '@page { @top-center { content: string(chapter); } }'
    . '</style>'
    . '<h2>Introduction</h2><p>Body text…</p>',
);
$doc->save(__DIR__ . '/running-header.pdf');

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

فعِّل عدّة أعلام معًا، وعامِل قناة الإرشاد كإشارة إلى أن بنيةً ما قد تدهورت. الأعلام مستقلّة؛ فعِّل فقط ما تستخدمه.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Exception\UnsupportedNamedPageException;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(new CssFeatureFlags(
    runningStrings: true,
    namedPagesAdvanced: true,
    runningElements: true,
    pageFloats: true,
));

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

try {
    $doc->writeHtml($html);
} catch (UnsupportedNamedPageException $e) {
    // A named @page rule tried to change page geometry (size/rotate/margin).
    // The engine fails closed rather than emit a misaligned page.
    throw $e;
}

$doc->save($out);

// Inspect $doc's advisory channel for HTML_RUNNING_ELEMENT_DEGRADED and
// HTML_PAGE_FLOAT_* before treating the output as final.

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

الأعلام الأربعة كلها مستقلّة ومُعطَّلة افتراضيًا. يُعطي العَلَم المُعطَّل مُخرجات متطابقة بايتًا ببايت. فعِّل فقط ما تستخدمه.
string() فارغة عندما يكون runningStrings مُعطَّلًا، بحكم التصميم. لا يوجد تحذير لحالة الإيقاف؛ فهي السلوك الافتراضي المُوثَّق.
العناصر المتكرّرة تُعيد عرض النص فقط. تُسقَط الصور والكتل المتداخلة داخل عنصر متكرّر مع HTML_RUNNING_ELEMENT_DEGRADED. تحقّق من قناة الإرشاد.
الصفحات المُسمّاة لا يمكنها تغيير الهندسة. أي قاعدة @page مُسمّاة/زائفة تُغيِّر الهندسة تطرح UnsupportedNamedPageException. اضبط حجم الصفحة والتدوير عبر Config، لا عبر قاعدة @page مُسمّاة.
عائمات الصفحة تُبقي الروابط في التدفّق. أي صندوق عائم يحتوي على تعليق رابط يرتدّ إلى التدفّق العادي مع تشخيص HTML_PAGE_FLOAT_*، لأن مستطيل الرابط يرتبط بموضعه في التدفّق.

الأداء

تضيف كل ميزة قدرًا محدودًا من العمل أحادي المرور: السلاسل المُسمّاة تُسجِّل قيمةً واحدة لكل عنصر string-set؛ والصفحات المُسمّاة تضيف حلّ صندوق هامش لكل صفحة؛ والعناصر المتكرّرة تلتقط مخزَّنًا نصيًا واحدًا لكل عنصر مُوقَف؛ وعائمات الصفحة تحجز شريطًا واحدًا لكل صفحة. ولا يحتفظ أيٌّ منها بشجرة مستند، فيُحفَظ نموذج الذاكرة O(عمق التداخل) للمُصيِّر التدفّقي. وميزانية الأداء performance_budget لكل صفحة (wall_ms: 1500، peak_mb: 64) لم تتغيّر.

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

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

المطابقة

العبارة	المواصفة	البند
`string-set` يُسجِّل سلسلةً مُسمّاة؛ و`string()` يحلّها في صندوق هامش صفحة.	W3C CSS Generated Content for Paged Media	§3
`position: running()` يُزيل عنصرًا من التدفّق؛ و`content: element()` يُعيد عرضه.	W3C CSS Generated Content for Paged Media	§5
الخاصية `page` و`@page <ident>` تنتقي سياق صفحة مُسمّاة.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` يُعوِّم صندوقًا في المحور الكتليّ إلى شريط صفحة.	W3C CSS Page Floats Level 3	§5

هذه تطبيقات معاينة لميزات وحدات في مجموعة العمل. يُطبِّق ⁨NextPDF⁩ مجموعةً فرعية أحادية المرور بحدود الإغلاق الآمن المُوثَّقة أعلاه. ويُتتبَّع الوضع المُتحقَّق منه لكل خاصية في مصفوفة دعم ⁨CSS⁩؛ ولا تُدَّعى أي مطابقة شاملة من طرفٍ إلى طرف هنا. ولا يُعاد إنتاج أي نص معياري.