แบ่งหน้าตาราง 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 เฉพาะสำหรับเค้าโครงที่ถูกลดทอนลงเท่านั้น คือเมื่อไม่มี page-break sink หรือเมื่อจำเป็นต้องย้ายแถวไปเป็นแถวแรกของหน้า ให้ถือว่าคำเตือนเป็นสัญญาณว่าควรปรับตารางให้ง่ายขึ้น ไม่ใช่สัญญาณว่าการทำงานล้มเหลว
วางส่วนหัวไว้ใน <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 — สถานะการรองรับสำหรับตารางและการแบ่งหน้า