HTML: النظام الفرعي لتصيير HTML+CSS إلى PDF

لمحة سريعة

يحوّل النظام الفرعي ⁨HTML⁩ لغة ترميز النص التشعّبي (⁨HTML⁩) وصفحات الأنماط المتتالية (⁨CSS⁩) إلى تدفّقات محتوى بصيغة المستندات المحمولة (⁨PDF⁩) عبر مرور أمامي واحد. وهو أكبر نظام فرعي في المحرّك وأعلاه مخاطرةً، ويضم 324 ملفًا ضمن src/Html/.

التثبيت

composer require nextpdf/core:^3

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

النظام الفرعي ⁨HTML⁩ هو مُصيِّر تدفّق أحادي المرور من ⁨HTML⁩+⁨CSS⁩ إلى ⁨PDF.⁩ واجهته العامة دالة واحدة: Document::writeHtml(). داخليًا، يقسّم HtmlParser المُدخل إلى رموز، ويحلّ الأنماط، ويحسب التخطيط، ويُصدِر مُعاملات ⁨PDF⁩ في مرور أمامي واحد، من دون الاحتفاظ بشجرة مستند.

يجب توضيح النطاق. هذا النظام الفرعي ليس مُصيِّر مستندات محتفظًا بها؛ فهو لا يحتفظ برسم بياني للعناصر، ولا يعيد تخطيط محتوى كُتب سابقًا، ولا يسمح بتغيير المُدخل بعد بدء التحليل. ويطبّق مجموعة فرعية منتقاة من ⁨CSS⁩ عند تثبيتات مواصفات ثابتة. يحكمه سجلّا قرارات معمارية (⁨ADRs⁩). يعرّف ⁨ADR-001⁩ نموذج التدفّق أحادي المرور وحدوده القصوى. ويعرّف ⁨ADR-010⁩ عقد الطبقات الأربع (تحليل ⁨CSS⁩، وحالة النمط، والتخطيط، والطلاء)، إلى جانب ملحقات الوسائط المقسّمة إلى صفحات والقياس.

صُنّف HtmlParser ضمن نطاق المخاطرة الحرجة في بيان الوحدة. تحمل خمسة ملفات تعليقات توضيحية موثّقة لمناطق الخطر: مُنسِّق HtmlParser ‏(مُقسِّم رموز تدفّقي، أكثر من 1000 سطر برمجي (⁨LOC⁩))، وHtmlStyleState ‏(أكثر من 100 حقل خاصية ⁨CSS⁩ مع نموذج وراثة قائم على المكدّس)، وHtmlBlockHandler ‏(توزيع الكتل المقترن بحالة النمط)، وFlexLayoutEngine ‏(قياس وتخطيط مرن كاملان)، وTableParser ‏(تقسيم ⁨colspan/rowspan⁩ إلى صفحات عبر فواصل الصفحات). عامِل أي تغييرات هنا على أنها عمل في وضع التخطيط.

استخدم هذه الصفحة بوصفها نقطة الدخول. راجع ⁨pipeline⁩ لمعرفة تسلسل المراحل، و⁨css-resolver⁩ لفهم التتالي والتحديد، و⁨layer-contracts-adr010⁩ لحدود الطبقات، و⁨streaming-constraints-adr001⁩ لنموذج عدم الاحتفاظ بالشجرة وحدوده القصوى.

النص من اليمين إلى اليسار وثنائي الاتجاه

يعرض writeHtml() المحتوى من اليمين إلى اليسار (⁨RTL⁩). عيّن خاصية ⁨CSS⁩ ‏direction: rtl على الجسم أو الجدول أو أي عنصر. يحلّ المحرّك الترتيب البصري باستخدام خوارزمية ⁨Unicode⁩ ثنائية الاتجاه (⁨UAX #9⁩) عبر المحرّك ثنائي الاتجاه في طبقة الطباعة — راجع الطباعة لتفاصيل BidiEngine. يُرتَّب المحتوى المختلط من اللاتينية والعربية والأرقام ترتيبًا صحيحًا، وتبقى الأرقام التي تأتي بعد العربية باتجاهها من اليسار إلى اليمين.

تأخذ العربية أيضًا تشكيلاً سياقيًا: يختار المحرّك الشكل الأولي أو الوسطي أو النهائي أو المعزول لكل حرف، ويطبّق رابطة ⁨Lam-Alef⁩. يحتاج التشكيل إلى خط مُسجَّل تغطّي خريطة محارفه كتلة ⁨Arabic Presentation Forms-B⁩؛ ولا يستطيع وجه لاتيني فقط، بما في ذلك خطوط ⁨standard-14⁩، رسم العربية. في الجداول، يُعاد ترتيب كل خلية وتُشكَّل على حدة، وتُحاذى إلى حافة البداية (اليمنى) تحت direction: rtl. ينطبق ⁨RTL⁩ على العربية والعبرية والفارسية والأردية؛ وتُعاد العبرية ترتيبًا لكن لا تُشكَّل.

عيّن الاتجاه باستخدام خاصية ⁨CSS⁩ ‏direction — فسمة ⁨HTML⁩ ‏dir لا تُربط بها. لم تُطبَّق بعد المحاذاة الأفقية لنص الكتل والنص السطري غير الجدولي، ولا text-align: justify. للحصول على فاتورة عربية قابلة للتشغيل والقائمة الكاملة للقيود الحالية، راجع عرض ⁨HTML⁩ عربي من اليمين إلى اليسار.

واجهة ⁨API⁩

الرمز	الموقع	الدور
`Document::writeHtml(string $html): static`	`src/Core/Concerns/HasTextOutput.php`	نقطة الدخول العامة. يصيّر ⁨HTML⁩ عند الموضع الحالي للمؤشّر.
`Document::createStandalone(): self`	`src/Core/Document.php`	إنشاء مستند مستقل.
`HtmlParser::parse(string $html): HtmlRenderResult`	`src/Html/HtmlParser.php`	مُنسِّق داخلي.
`HtmlRenderResult`	`src/Html/HtmlRenderResult.php`	نتيجة غير قابلة للتغيير: الدفق، وموضع المؤشّر النهائي، والخطوط المستخدمة.
`DefaultHtmlSecurityPolicy`	`src/Html/DefaultHtmlSecurityPolicy.php`	السياسة الافتراضية للوسوم والسمات و⁨CSS⁩ ومُحدِّد موقع المورد الموحّد (⁨URL⁩).
`HtmlSecurityPolicyInterface`	`src/Contracts/HtmlSecurityPolicyInterface.php`	عقد السياسة للسياسات المخصّصة.

عيّنة برمجية — البدء السريع

المصدر: examples/08-html-basic.php.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Basic');
$doc->addPage();
$doc->writeHtml('<h1 style="color:#1E3A8A;">HTML Rendering</h1><p>Direct to PDF.</p>');
$doc->save(__DIR__ . '/output/08-html-basic.pdf');

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

تعرض هذه العيّنة تقريرًا جدوليًا يتضمّن كتلة نمط مضمّنة، وهي مبنية على examples/09-html-table.php.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;
use NextPDF\Exception\HtmlParsingException;

function renderInventory(string $rowsHtml, string $out): void
{
    $doc = Document::createStandalone();
    $doc->setTitle('Inventory');
    $doc->addPage();

    $html = '<style>table { width: 100%; } '
          . 'th { background-color: #1E3A8A; color: #FFFFFF; }</style>'
          . '<table border="1" cellpadding="5">' . $rowsHtml . '</table>';

    try {
        $doc->writeHtml($html);
    } catch (HtmlParsingException $e) {
        // Input cap, element cap (50,000), or nesting cap (100). Do not retry.
        throw $e;
    }

    $doc->save($out);
}

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

مجموعة ⁨CSS⁩ فرعية منتقاة. يُثبَّت الدعم على مستوى كل وحدة. تحقّق من مصفوفة دعم ⁨CSS⁩ قبل الاعتماد على أي خاصية.
الحدود القصوى الصارمة تُطلِق استثناءات. يُطلِق كل من حدّ المُدخل البالغ 10 ⁨MB⁩، وحدّ 50,000 عنصر، وحدّ التداخل البالغ 100 مستوى HtmlParsingException. راجع قيود التدفّق.
لا إعادة تخطيط. يكتب المُصيِّر المُخرَج مرة واحدة بترتيب المستند؛ ولا تستطيع الأنماط المتأخّرة تغيير مُخرَج سابق.
:has() محجوب خلف الميزة التجريبية css.has.
نظام فرعي حرج المخاطرة. خمسة ملفات مُعلَّمة بوصفها مناطق خطر. استخدم وضع التخطيط عند إجراء تغييرات ضمن src/Html/.

قيود التدفّق أحادي المرور (⁨ADR-001⁩)

لا يحتفظ المُصيِّر بأي شجرة مستند، ويُجري مرورًا أماميًا واحدًا. حدود العناصر والتداخل والمُدخل حدود صارمة. للاطّلاع على التفاصيل الكاملة وعقد سلامة العامل، راجع قيود التدفّق (⁨ADR-001⁩).

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

يُفصَل تحليل ⁨CSS⁩ وحالة النمط والتخطيط والطلاء في أربع طبقات ذات عقود أحادية الاتجاه، إلى جانب ملحقات الوسائط المقسّمة إلى صفحات والقياس. للاطّلاع على التفاصيل الكاملة، راجع عقود الطبقات (⁨ADR-010⁩).

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

ذاكرة حالة النمط والمؤشّر هي ⁨O⁩(⁨nesting depth⁩)، وليست ⁨O⁩(⁨element count⁩). قيمة performance_budget لكل صفحة هي peak_mb: 64. حدّ 50,000 عنصر هو السقف الصارم؛ قسّم المُدخلات الأكبر عبر استدعاءات متعددة لـ writeHtml(). للاطّلاع على التفاصيل، راجع قيود التدفّق.

الأداء

الاجتياز هو ⁨O⁩(⁨token count⁩). يضيف تحديد حجم أعمدة الجدول مسحًا محدودًا لصفوف كل جدول. ويضيف المسح المُسبق الاختياري لـ :has() مرورًا محدودًا واحدًا على قائمة الرموز. يفرض اختبار أداء خط تصيير ⁨HTML⁩ المرجعي بوّابة انحدار بنسبة %5 ‏(عمل مدموج، طلب سحب (⁨PR⁩) ‏#564). قيمة performance_budget لكل صفحة (wall_ms: 1500، peak_mb: 64) هي السقف التشغيلي.

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

يفرض DefaultHtmlSecurityPolicy قائمة سماح للوسوم والسمات وخصائص ⁨CSS⁩ ومخطّطات ⁨URL⁩، إضافةً إلى سقف مُدخل بحجم 10 ⁨MB⁩ وسقف تداخل بـ 100 مستوى، بشكل مستقل عن المحلّل. قائمة سماح خصائص ⁨CSS⁩ هي السقف الأمني. أما جدول دعم وقت التشغيل فهو سقف قدرات منفصل. نفّذ HtmlSecurityPolicyInterface لتوفير سياسة أكثر صرامة. ويحكم DefaultExternalResourcePolicy جلب الموارد الخارجية على نحو منفصل.

في قيم href وsrc للصور، ترفض قائمة سماح ⁨URL⁩ أيضًا المسارات المتجذّرة بشرطة خلفية (\…) ومسارات اصطلاح التسمية الموحّد (⁨UNC⁩) ‏(\\host\share)، إلى جانب الرفض القائم للمسارات النسبية بالبروتوكول (//) وقائمة السماح التي تقتصر على ⁨http⁩(⁨s⁩) أو المسارات النسبية. تُطبَّع الشرطات الخلفية إلى شرطات أمامية قبل الفحص، بحيث لا يستطيع تضمين ملف محلي بمسار مطلق على ⁨Windows⁩ أو جلب مشاركة كتلة رسائل الخادم (⁨SMB⁩) المرور عبر فرع “لا مخطّط، إذًا نسبي”. لا يحمل أيٌّ من المسارين مخطّط مُعرِّف المورد الموحّد (⁨URI⁩).

مقتطف من مصفوفة دعم ⁨CSS⁩ ‏(الصفوف المتحقَّق منها فقط)

لا تعيد هذه الصفحة ذكر الدعم لكل خاصية. تُعدّ مصفوفة دعم ⁨CSS⁩ المرجع الوحيد لحالة كل وحدة متحقَّق منها من وحدات اتحاد الشبكة العالمية (⁨W3C⁩)، بما في ذلك تمييز الوحدات المتحقَّق منها عن الوحدات المُدّعى بها.

المطابقة

يطبّق النظام الفرعي مجموعة ⁨CSS⁩ فرعية منتقاة عند تثبيتات مواصفات ثابتة. تُوثَّق تعيينات المواصفة السلوكية للتتالي باستخدام مُعرِّفات البنود والمقاطع في ⁨css-resolver⁩. تظهر حالة المطابقة لكل وحدة في مصفوفة دعم ⁨CSS⁩.

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

قدرة ⁨Enterprise.⁩ يوسّع ⁨Premium⁩ تغطية ⁨CSS⁩ ‏(الطباعة المتقدّمة والوحدات الإضافية) على خط الأنابيب أحادي المرور نفسه. تظل البنية والحدود القصوى وعقود الطبقات كما هي عبر الإصدارات. راجع مصفوفة دعم ⁨CSS⁩.