تخطيط جدول HTML

لمحة سريعة

استخدم هذه الوصفة لعرض جدول ⁨HTML⁩ يتضمن رأسًا وخلايا بمحاذاة محددة وحدودًا وصف تذييل. تُعد الجداول وحدة “مُتحقق منها” في مصفوفة دعم ⁨CSS⁩. تتبع الوصفة examples/09-html-table.php.

التثبيت

composer require nextpdf/core:^3

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

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

يستخدم محرك ⁨HTML⁩ خط أنابيب مخصصًا للجداول (src/Html/Table/). يجمع TableParser الصفوف والخلايا في مخزن مؤقت قصير العمر، ثم يتولى ⁨NextPDF⁩ تخطيط الجدول ورسمه. هذا هو الانحراف الوحيد المُعترف به عن نموذج عدم الاحتفاظ بـ ⁨DOM⁩ في ⁨ADR-001.⁩ المخزن المؤقت قصير العمر ومحصور في نطاق حاويته، وليس ⁨DOM⁩ دائمًا.

تتبع عروض الأعمدة نموذج جداول ⁨CSS.⁩ يخطّط ⁨NextPDF⁩ الجدول عند عرض مُستخدَم معيّن، ثم تحدّد خوارزمية تحجيم الأعمدة العرض المُستخدَم لكل عمود (⁨W3C CSS Table Level 3⁩). مع table-layout: fixed، يُتجاهل محتوى الخلية عند حساب العرض. وبدلًا من ذلك، يوجّه الصف الأول وعروض الأعمدة الصريحة عملية التخطيط (⁨W3C CSS Table Level 3⁩).

يُصنَّف ⁨CSS Table Level 3⁩ على أنه مُتحقق منه في المصفوفة. يستند هذا التصنيف إلى أربعة مصادر: src/Html/Table/، ومجموعة اختبارات وحدة الجداول، واختبارات ⁨TableParser⁩، وملفات ⁨PDF⁩ الذهبية المُصطنعة.

واجهة ⁨API⁩

اعرض الجداول باستخدام writeHtml(string $html): static ‏(NextPDF\Core\Concerns\HasTextOutput). يدعم المحرك ترميز الجداول القياسي. الوسوم المدعومة هي table وthead وtbody وtfoot وtr وth وtd. السمات المدعومة هي border وcellpadding وcellspacing وcolspan، إضافةً إلى style على مستوى الخلية. يُولَّد جدول ⁨PHPDoc⁩ الكامل من المصدر.

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

$doc->writeHtml(
    '<table border="1" cellpadding="5"><tr><th>SKU</th><th>Qty</th></tr>'
    . '<tr><td>NPD-CORE</td><td style="text-align: right;">1</td></tr></table>'
);

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

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

يمكن تشغيل هذا المثال المكتفي ذاتيًا في بيئة الاختبار. وهو يعكس examples/09-html-table.php ويعرض رأسًا منسّقًا، وخلفيات صفوف متناوبة، وأعمدة رقمية بمحاذاة محددة، وإجماليًا في التذييل.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Table');
$doc->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Product Inventory Report</h1>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 10%;">#</th>
            <th style="width: 45%;">Product</th>
            <th style="width: 20%; text-align: center;">SKU</th>
            <th style="width: 25%; text-align: right;">Price</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>1</td>
            <td>NextPDF Core License</td>
            <td style="text-align: center;">NPD-CORE</td>
            <td style="text-align: right;">$0.00</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>2</td>
            <td>NextPDF Pro License</td>
            <td style="text-align: center;">NPD-PRO</td>
            <td style="text-align: right;">$299.00</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="background-color: #1E293B; color: #FFFFFF; font-weight: bold;">
            <td colspan="3" style="text-align: right;">Grand total:</td>
            <td style="text-align: right;">$299.00</td>
        </tr>
    </tfoot>
</table>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/html-table-layout.pdf');

echo "Wrote html-table-layout.pdf\n";

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

Wrote html-table-layout.pdf

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

العروض المئوية. تُحسَب النسب المئوية في width الخاص بالعمود نسبةً إلى عرض الجدول المُستخدَم. تطبّع خوارزمية تحجيم الأعمدة النسب المئوية التي لا يبلغ مجموعها 100. لا تفترض عروضًا بالبكسل بدقة مطلقة.
colspan. تشارك الخلية الممتدة في توزيع العرض على الأعمدة التي تغطيها. إجمالي التذييل الذي يمتد عبر معظم الأعمدة نمط شائع ومدعوم.
نموذج الحدود. في بعض إعدادات الجداول، يختلف الإعداد الافتراضي لـ border-collapse عن القيمة الابتدائية في ⁨CSS.⁩ حدّده مباشرةً عندما يكون عرض الحدود مهمًا.
امتداد الصف عبر فواصل الصفحات. يمكن لخلية ممتدة عبر الصفوف أن تتجاوز حدود الصفحة؛ عندئذٍ يُجزّئ مُرقِّم امتداد الصفوف تلك الخلية (⁨ADR-007⁩). يمكن أن تثير الخلية الشديدة الطول التي يتعذّر تقسيمها UnsplittableContentException.
الخلايا الفارغة. تظل <td> الفارغة تشغل خانتها في الشبكة، ولا تُطوى بعيدًا.

الأداء

مخزن الجدول المؤقت قصير العمر ومحصور في نطاق حاويته. تكلفة التحليل خطية بالنسبة إلى عدد الخلايا، إضافةً إلى مرور تحجيم الأعمدة بمقدار ⁨O⁩(⁨rows x cols⁩). الميزانية هي wall_ms: 1500, peak_mb: 96. أبقِ الجدول الواحد ضمن حد عُقَد ⁨ADR-020⁩ البالغ 5,000 عُقدة لكل سياق.

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

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

وحدة ⁨W3C⁩	المستوى	الحالة	الدليل
جداول ⁨CSS⁩ ‏(`css_tables_3`)	3	مُتحقق منه	`src/Html/Table/`، `tests/Unit/Html/Table/` + اختبارات ⁨TableParser⁩ + ملفات ⁨PDF⁩ الذهبية
تخطيط الصندوق المرن في ⁨CSS⁩ ‏(`css_flexbox_1`)	1	مُتحقق منه	`src/Html/Flex/`، `tests/Unit/Html/Flex/`
تخطيط الشبكة في ⁨CSS⁩ ‏(`css_grid_1`)	1	مُتحقق منه	`src/Html/Grid/`، مجموعة بيانات ⁨WPT⁩
التتالي والوراثة في ⁨CSS⁩ ‏(`css_cascade_3`)	3	مُتحقق منه	`src/Html/Cascade/`

يُصنَّف background-color، المُستخدَم هنا لتخطيط الصفوف، على أنه “مُعلَن” في المصفوفة. وبموجب تدقيق ⁨Phase 0⁩، يقتصر نطاقه على خلية الجدول. يُعرَض لصفوف الجدول، لكنه غير مُدرَج بوصفه “مُتحقق منه”.

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

مخزن الجدول المؤقت هو الاستثناء المُوثَّق لنموذج التدفق. وهو قصير العمر ومحدود، وليس ⁨DOM⁩ عامًا. لا تعتمد على الجدول لتوفير سياق شجري للمحتوى الموجود خارجه.

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

تقرأ FormattingContextFactory::startTable() ⁨CSS⁩ عبر عقد طبقة التخطيط، ولا تحلّل $css[...] الخام في مسار الإرسال. تبقى الواجهة العامة writeHtml().

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

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

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

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

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
تُحدَّد عروض الأعمدة المُستخدَمة بواسطة خوارزمية تحجيم أعمدة الجدول عند عرض الجدول المُستخدَم.	⁨W3C CSS Table Level 3⁩	⁨css_tables_3⁩#⁨x1.x4.x9.x3⁩
في الوضع الثابت، يُتجاهل محتوى الخلية عند حساب عرض العمود.	⁨W3C CSS Table Level 3⁩	⁨css_tables_3⁩#⁨x1.x4.x5.x1.p6⁩

تُبيّن هذه الوصفة كيف يعرض ⁨NextPDF⁩ جداول ⁨HTML⁩ المدعومة. يُعد ⁨CSS Table Level 3⁩ مُتحققًا منه في مصفوفة الدعم، وتُصنَّف وحدات ⁨CSS⁩ الأخرى المُستخدَمة هنا وفق تلك المصفوفة.

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

لا ينطبق.