ترقيم جدول HTML كبير عبر صفحات متعددة

لمحة سريعة

مرّر <table> كبيرًا واحدًا إلى writeHtml(). يوزّعه المحرك على صفحات PDF بالعدد الذي تحتاج إليه الصفوف. يتكرر <thead> في أعلى كل صفحة، فتتعامل كل صفحة معه بوصفه جدولًا كاملًا. تعرض هذه الوصفة تقريرًا من 91 صفًا يتدفّق عبر عدة صفحات. لست بحاجة إلى تقسيم الجدول بنفسك أو حساب فواصل الصفحات.

التثبيت

composer require nextpdf/core

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

عندما يتجاوز ارتفاع الجدول صفحة واحدة، أبقِه عنصر <table> واحدًا. يقيس المحرك كل صف، ويملأ الارتفاع القابل للاستخدام في الصفحة، ثم يفتح صفحة جديدة ويتابع الجدول نفسه. ويعرض صفوف <thead> مجددًا في أعلى كل صفحة استمرار. تحافظ صفحات الاستمرار على الهامشين العلوي والسفلي للمستند، فيبدأ الصف الأول في الصفحة الجديدة أسفل الهامش العلوي، لا عند حافة الصفحة.

ضع خلايا الرأس في <thead> وصفوف البيانات في <tbody>. لا يتكرر إلا <thead>. اجعل كل صف قابلًا للتقسيم. لا يمكن ترقيم صف واحد يزيد ارتفاعه على ارتفاع الصفحة القابل للاستخدام، ويثير UnsplittableContentException.

واجهة API

الرمز	الموضع	الدور
`Document::writeHtml(string $html): static`	`NextPDF\Core\Concerns\HasTextOutput`	اعرض HTML ورقّم الجداول عبر الصفحات حسب الحاجة.
`Document::createStandalone(): self`	`NextPDF\Core\Document`	أنشئ مستندًا مستقلًا.
`Document::addPage(): static`	`NextPDF\Core\Document`	افتح الصفحة الأولى واضبط حجم الصفحة وهوامشها.

نموذج الكود — البدء السريع

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$rows = '';
for ($i = 1; $i <= 91; $i++) {
    $rows .= "<tr><td>{$i}</td><td>Item {$i}</td><td>In stock</td></tr>";
}

$doc = Document::createStandalone();
$doc->addPage();
$doc->writeHtml(
    '<table>'
    . '<thead><tr><th>#</th><th>Name</th><th>Status</th></tr></thead>'
    . "<tbody>{$rows}</tbody>"
    . '</table>'
);
$doc->save(__DIR__ . '/large-table.pdf');

تتدفّق الصفوف الـ91 عبر عدة صفحات، ويتكرر رأس #/Name/Status في كل صفحة.

نموذج الكود — للإنتاج

ينسّق هذا المثال المستقل الرأس، ويعرض الصفوف بخلفيات متناوبة، ويكتب ملف PDF إلى المسار الذي توفّره منظومة الاختبار.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$rows = '';
for ($i = 1; $i <= 91; $i++) {
    $bg = $i % 2 === 0 ? '#F8FAFC' : '#FFFFFF';
    $rows .= "<tr style=\"background-color: {$bg};\">"
        . "<td style=\"border: 1px solid #CBD5E1; padding: 4px;\">{$i}</td>"
        . "<td style=\"border: 1px solid #CBD5E1; padding: 4px;\">Item {$i}</td>"
        . "<td style=\"border: 1px solid #CBD5E1; padding: 4px;\">In stock</td>"
        . '</tr>';
}

$html = <<<HTML
<table style="width: 100%; border-collapse: collapse;">
  <thead>
    <tr style="background-color: #1E3A8A; color: #FFFFFF;">
      <th style="border: 1px solid #1E3A8A; padding: 6px;">#</th>
      <th style="border: 1px solid #1E3A8A; padding: 6px;">Name</th>
      <th style="border: 1px solid #1E3A8A; padding: 6px;">Status</th>
    </tr>
  </thead>
  <tbody>{$rows}</tbody>
</table>
HTML;

$doc = Document::createStandalone();
$doc->setTitle('Inventory report');
$doc->addPage();
$doc->writeHtml($html);

$out = getenv('NEXTPDF_OUT');
$doc->save($out !== false ? $out : __DIR__ . '/paginate-large-html-tables.pdf');

echo "Wrote the paginated table PDF\n";

هوامش صفحة الاستمرار

تستخدم صفحات الاستمرار الهامشين العلوي والسفلي للمستند. بعد فاصل الصفحة، يبدأ الصف الأول أسفل الهامش العلوي، ويتوقف الصف الأخير قبل بلوغ الهامش السفلي. يمنع ذلك اقتطاع الجدول الطويل عند حافة الصفحة. وتنطبق القاعدة نفسها على الكتل والجداول الممتدة عبر عدة صفحات.

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

لا تظهر تحذيرات الترقيم على صفحات عند النجاح. عندما يتدفّق الجدول بنظافة عبر الصفحات، لا يُصدر أي تحذير. ولا يثير المحرك تحذير TABLE_ROW_OVERFLOW إلا عند تدهور التخطيط: حين لا يتوفر موضع يستوعب فاصل الصفحة، أو حين يجب نقل صف إلى بداية صفحة. عامِل التحذير بوصفه إشارة إلى تبسيط الجدول، لا بوصفه فشلًا.
ضع الرأس في <thead>. لا تتكرر إلا صفوف <thead>. أما صف الرأس المتروك في <tbody> فلا يظهر إلا مرة واحدة.
يجب أن تكون الصفوف قابلة للتقسيم. يثير صفّ واحد يزيد ارتفاعه على ارتفاع الصفحة القابل للاستخدام UnsplittableContentException. جزّئ محتوى ذلك الصف، أو اختصره.
يتدهور rowspan عبر الفاصل. تُجزَّأ خلية rowspan التي تعبر حدود الصفحة (ADR-007). وبالنسبة للتجميعات التي يجب أن تبقى متماسكة عبر الترقيم على صفحات، استخدم صف عنوان فئة بدلًا منها. راجع ميزات CSS غير المدعومة.

الأداء

يتناسب العرض تناسبًا خطيًا مع عدد الصفوف. يبثّ المحرك المُخرَج صفحة بصفحة، ولا يحتفظ أبدًا بشجرة مستند كاملة، لذلك لا يزداد استهلاك الذاكرة للجداول الطويلة مع عدد الصفحات. ميزانية هذه الوصفة هي wall_ms: 2000, peak_mb: 96.

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

تحقّق من عدد الصفوف وطول الخلايا في البيانات المُقدَّمة من المستخدم لإبقاء حجم المُخرَج ضمن الحدود المطلوبة. يعرض المحرك النص كما هو بدلًا من تفسيره، ولا يشغّل أي سكربت.

المطابقة

العبارة	المواصفة	البند	reference_id
تتكرر مجموعة رأس الجدول عبر حاويات التجزئة التي يُقسَّم الجدول إليها.	W3C CSS Tables 3	css_tables_3#x1.x7.x2	53622ccb1bce2a0cc53bd70919fa4633a9376e2050f63a31a3fde9cb6595ec78

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

غير منطبق.

انظر أيضًا

HTML: نظام HTML+CSS الفرعي للعرض إلى PDF — العرض أحادي التمريرة وسلوك الترقيم على الصفحات.
تخطيط جدول HTML — تحجيم الأعمدة وcolspan والحدود.
ترقيم محتوى HTML الطويل على صفحات — فواصل الصفحات للمحتوى الكتلي المختلط.
مصفوفة دعم CSS — حالة الدعم للجداول والترقيم على صفحات.