تنسيق HTML باستخدام CSS

لمحة سريعة

تطبّق هذه الوصفة صفحات الأنماط المتتالية ‏(⁨CSS⁩)‏ على محتوى لغة ترميز النص التشعبي ‏(⁨HTML⁩)‏. وتستخدم سمات style المضمّنة وكتلة <style>. وستتعرّف أيضًا على طريقة التأكد من توثيق الخاصية قبل الاعتماد عليها.

التثبيت

composer require nextpdf/core:^3

استخدم هذا القيد للحزمة nextpdf/core. يعمل المثال على ⁨PHP⁩ 8.4.

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

يحلّ محرك ⁨HTML⁩ التنسيقات عبر تتالي ⁨CSS.⁩ ويحدّد التتالي التنسيق الذي تكون له الغلبة عندما تستهدف عدة قواعد العنصر نفسه. يقرأ المحرك كتلة <style> المُدخَلة أولًا، ثم سمات style المضمّنة. ويطابقهما مع العناصر، ثم يحسب النتيجة وفق ترتيب التتالي. تُصنِّف مصفوفة الدعم وحدة ⁨CSS Cascading and Inheritance⁩ على أنها مُوثَّقة، أي إن مجموعة تثبيتات مخصّصة تغطي سلوك التتالي والوراثة.

خصائص عرض النص، مثل text-align وtext-indent وletter-spacing، مُعرَّفة في جدول خصائص وحدة ⁨CSS Text⁩ التابعة لاتحاد الشبكة العالمية ‏(⁨W3C⁩)‏ ‏(⁨W3C CSS Text Level 3⁩)‏. ويعتمد اختيار الخط على نموذج ⁨CSS Fonts.⁩ يضبط الاختصار font كلًّا من font-style وfont-variant وfont-weight وfont-size وfont-family معًا ‏(⁨W3C CSS Fonts Level 3⁩)‏.

تُتابَع حالة الدعم بحسب وحدة ⁨W3C⁩، وتخضع لتدقيق صدقيّ. قد تكون الخاصية مُنفَّذة، لكنها تفتقر إلى تثبيت وحدة مخصص؛ وفي هذه الحالة تُصنَّف على أنها “⁨Claimed⁩”، لا “⁨Verified⁩”. تعامَل مع “⁨Claimed⁩” على أنها أفضل جهد متاح، وتحقق من النتيجة المرئية لمحتواك. وتعامَل مع “⁨Verified⁩” على أنها مدعومة بمجموعة تثبيتات ناجحة.

واجهة ⁨API⁩

تحكّم في التنسيق من خلال ⁨HTML⁩ الذي تمرّره إلى writeHtml(string $html): static ‏(NextPDF\Core\Concerns\HasTextOutput)‏. لا توجد واجهة برمجة تطبيقات ‏(⁨API⁩)‏ منفصلة لـ ⁨CSS⁩؛ إذ يعمل التتالي داخليًا. يُولَّد جدول ⁨PHPDoc⁩ الكامل من المصدر.

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

$doc->writeHtml(
    '<style>.lead { color: #1E3A8A; text-align: center; }</style>'
    . '<p class="lead">Styled with a style block.</p>'
);

$doc->save(__DIR__ . '/out.pdf');

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

يمكن تشغيل هذا المثال المكتفي ذاتيًا في بيئة الاختبار. وهو يختبر كتلة <style>، ومحدِّدات الفئات، والتنسيقات المضمّنة، ومسار عائلة الخط ووزنه ضمن font.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('CSS Styling');
$doc->addPage();

$html = <<<'HTML'
<style>
    h1        { color: #1E3A8A; }
    .lead     { color: #D97706; font-size: 14px; }
    .callout  { background-color: #EFF6FF; padding: 8px; border: 1px solid #BFDBFE; }
    .centered { text-align: center; }
</style>

<h1>Styling HTML with CSS</h1>

<p class="lead">This paragraph is styled through a class selector in a
style block.</p>

<p class="callout">This paragraph has a background, padding, and a border
from a class selector.</p>

<p class="centered" style="font-weight: bold;">Centered, with an inline
override for weight.</p>

<p style="color: #6B7280; font-size: 9px;">Inline style only.</p>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/style-with-css.pdf');

echo "Wrote style-with-css.pdf\n";

الخرج القياسي المتوقع ‏(⁨STDOUT⁩)‏:

Wrote style-with-css.pdf

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

• ترتيب التتالي. في التتالي، يغلب style المضمّن على محدِّد كتلة <style> عند تساوي التحديد. إذا رأيت لونًا غير متوقع، فتحقق أولًا من وجود تجاوز مضمّن.
• “⁨Claimed⁩” مقابل “⁨Verified⁩”. تُصنَّف text-align وtext-indent وcolor على أنها “⁨Claimed⁩” في المصفوفة. فهي مُنفَّذة، لكنها تفتقر إلى تثبيت وحدة مخصص. تُعرَض هذه الخصائص، لكن تحقق من الخرج المرئي قبل اعتمادها نهائيًا في الإنتاج.
• لا توجد شجرة محتفظ بها. لا يحتفظ محرك البث، الموصوف في سجل قرار البنية ‏(⁨ADR-001⁩)‏، بشجرة مستند، لذا يتعذر عليه تطبيق محدِّد يجعل عنصرًا شقيقًا لاحقًا يعيد تنسيق عنصر سابق. ونتيجة لذلك، تكون المحدِّدات غير المعتمدة على الترتيب مقيَّدة.
• خاصية غير مدعومة. تُتجاهَل الخاصية غير المدعومة، ولا تُطلَق على هيئة خطأ. تحقق من المصفوفة قبل الاعتماد عليها.
• مساحات الألوان. تُحلَّل قيم ⁨Lab⁩ و⁨LCH⁩ و⁨OKLab⁩، لكن دقة مساحة الألوان في تنسيق المستندات المحمول ‏(⁨PDF⁩)‏ لهذه الدوال غير مؤكَّدة (المصفوفة: “⁨Claimed⁩” لـ ⁨CSS Color 4⁩).

الأداء

يُحلّ التتالي في تمريرة واحدة. وتظل التكلفة خطية بالنسبة إلى عدد الرموز، ⁨O⁩(⁨n⁩). الميزانية هي wall_ms: 1500, peak_mb: 96. تضيف كتلة <style> تكلفة تحليل محدِّدات تُدفَع مرة واحدة وتتناسب مع عدد القواعد.

مقتطف من مصفوفة دعم ⁨CSS⁩ (صفوف “⁨Verified⁩” فقط)

يعرض هذا المقتطف صفوف ⁨Verified⁩ فقط من مصفوفة دعم ⁨CSS⁩ الخاضعة لتدقيق صدقيّ.

وحدة ⁨W3C⁩	المستوى	الحالة	الدليل
⁨CSS Cascading and Inheritance⁩ ‏(css_cascade_3)‏	3	⁨Verified⁩	src/Html/Cascade/، tests/Unit/Html/Cascade/
⁨CSS Cascading⁩ ‏(css_cascade_4)‏	4	⁨Verified⁩	اختبارات Cascade/Layer/ + ⁨revert/layer⁩
⁨CSS Cascading⁩ ‏(css_cascade_5)‏	5	⁨Verified⁩	مجموعتا AtRule/Layer/ + Cascade/Layer/
⁨CSS Fonts⁩ ‏(css_fonts_3)‏	3	⁨Verified⁩	src/Html/Font/، tests/Unit/Font/ + اختبارات ⁨FontResolver⁩
⁨CSS Fonts⁩ ‏(css_fonts_4)‏	4	⁨Verified⁩	src/Html/FontFace/، tests/Unit/Html/FontFace/

text-align وtext-indent وcolor وbackground-color مُصنَّفة على أنها “⁨Claimed⁩” في المصفوفة. ويستبعدها الجدول من صفوف “⁨Verified⁩” عن قصد.

قيود البث ذي التمريرة الواحدة ‏(⁨ADR-001⁩)‏

يعمل التتالي على قائمة رموز مُبثوثة دون نموذج كائن المستند ‏(⁨DOM⁩)‏، لذا تُحلّ المحدِّدات وفق سياق ترتيب المستند. حالات محدِّدات الشجرة الكاملة مقيَّدة وفقًا لـ ⁨ADR-006.⁩ اكتب ⁨CSS⁩ يعتمد فقط على ترتيب المستند وسياق العناصر السابقة.

عقود الطبقات ‏(⁨ADR-010⁩)‏

يخصّ تحليل ⁨CSS⁩ طبقة التتالي، ويجب ألّا يقرأ توزيع التخطيط قيم $css[...] الخام مباشرةً. الواجهة العامة هي مُدخَل ⁨HTML.⁩ لا توجد طريقة مدعومة لحقن تنسيقات محسوبة بعد التتالي.

ميزانية الذاكرة للمستندات الكبيرة

يحتفظ التتالي بمجموعة القواعد النشطة ومكدّس الأنماط للدفع والسحب، وليس بشجرة عُقَد. تلتزم السياقات المحدودة بالحاوية بميزانية ⁨ADR-020⁩ (5,000 عُقدة لكل سياق، وسقف نشط قدره 50 ⁨MB⁩). تزيد صفحات الأنماط الكبيرة ذاكرة مجموعة القواعد خطيًا، لذا أبقِ عدد المحدِّدات محدودًا.

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

لا يمكن لـ ⁨CSS⁩ في ⁨HTML⁩ غير الموثوق تنفيذ تعليمات برمجية، لكنه يمكن أن يؤثر في التخطيط وفي مراجع الموارد، مثل background-image. لا تجلب سياسة الموارد الخارجية الافتراضية عناوين ⁨URL⁩ بعيدة عشوائية. طهّر أي ⁨HTML⁩ و⁨CSS⁩ تجمعه من إدخال المستخدم قبل عرضه.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
خصائص النص (⁨text-align⁩ و⁨text-indent⁩ و⁨letter-spacing⁩) مُعرَّفة في جدول خصائص ⁨CSS Text.⁩	⁨W3C CSS Text Level 3⁩	⁨css_text_3⁩#⁨x1.x24⁩
يضبط الاختصار ⁨font⁩ كلًّا من ⁨font-style⁩ و⁨font-variant⁩ و⁨font-weight⁩ و⁨font-size⁩ و⁨font-family.⁩	⁨W3C CSS Fonts Level 3⁩	⁨css_fonts_3⁩#⁨x2.x6.x7.p2⁩

توضّح هذه الوصفة كيف يطبّق ⁨NextPDF⁩ مجموعة فرعية مدعومة من ⁨CSS⁩؛ وهي لا تؤكّد دعم ⁨CSS⁩ الكامل. للاطلاع على الحالة المُوثَّقة لكل وحدة، راجع مصفوفة دعم ⁨CSS.⁩

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

غير منطبق.

انظر أيضًا

• عرض ⁨HTML⁩ في صفحة ⁨PDF⁩
• تخطيط جدول ⁨HTML⁩
• مصفوفة دعم ⁨CSS⁩