จัดวางตาราง HTML

ภาพรวมโดยย่อ

ใช้สูตรนี้เพื่อเรนเดอร์ตาราง Hypertext Markup Language (HTML) ที่มีส่วนหัว เซลล์ที่จัดแนว เส้นขอบ และแถวส่วนท้าย ตารางนี้เป็นโมดูลระดับ Verified ในเมทริกซ์การรองรับ Cascading Style Sheets (CSS) สูตรนี้อ้างอิงจาก examples/09-html-table.php

การติดตั้ง

composer require nextpdf/core:^3

คำสั่งนี้จะติดตั้งแพ็กเกจ nextpdf/core ตัวอย่างนี้ทำงานบน PHP 8.4

ภาพรวมเชิงแนวคิด

เอนจิน HTML ใช้ไปป์ไลน์ตารางเฉพาะ (src/Html/Table/) โดย TableParser รวบรวมแถวและเซลล์ไว้ในบัฟเฟอร์อายุสั้น จากนั้น NextPDF จึงจัดวางและวาดตาราง นี่เป็นข้อยกเว้นเพียงรายการเดียวที่ยอมรับจากโมเดล Document Object Model (DOM) แบบไม่คงสถานะตาม ADR-001 บัฟเฟอร์นี้มีอายุสั้น จำกัดขอบเขตอยู่ภายในคอนเทนเนอร์ของตน และไม่ใช่ DOM แบบคงสถานะ

ความกว้างของคอลัมน์เป็นไปตามโมเดล CSS Table โดย NextPDF จัดวางตารางตามความกว้างที่ใช้งานที่กำหนดไว้ จากนั้นอัลกอริทึมการกำหนดขนาดคอลัมน์จะกำหนดความกว้างที่ใช้งานของแต่ละคอลัมน์ (W3C CSS Table Level 3) เมื่อใช้ table-layout: fixed เนื้อหาของเซลล์จะถูกละเว้นในการคำนวณความกว้าง และใช้แถวแรกกับความกว้างของคอลัมน์ที่ระบุอย่างชัดเจนเป็นตัวกำหนดเค้าโครงแทน (W3C CSS Table Level 3)

CSS Table Level 3 ได้รับการจัดระดับเป็น Verified ในเมทริกซ์ โดยมีแหล่งข้อมูลสี่แหล่งที่สนับสนุนระดับนี้ ได้แก่ src/Html/Table/ ชุดทดสอบหน่วย Table การทดสอบ TableParser และ golden 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 ให้กำหนดค่าโดยตรงเมื่อการเรนเดอร์เส้นขอบมีความสำคัญ
Rowspan ข้ามการแบ่งหน้า เซลล์ที่ขยายข้ามแถวสามารถข้ามขอบเขตหน้าได้ เมื่อเกิดกรณีดังกล่าว ตัวแบ่งหน้า rowspan จะแยกเซลล์นั้นออกเป็นส่วน (ADR-007) เซลล์ที่สูงมากซึ่งไม่สามารถแยกได้อาจทำให้เกิด UnsplittableContentException
เซลล์ว่าง <td> ที่ว่างเปล่ายังคงครอบครองช่องในกริดของตน เซลล์ดังกล่าวจะไม่ถูกยุบหายไป

ประสิทธิภาพ

บัฟเฟอร์ตารางมีอายุสั้นและจำกัดขอบเขตอยู่ภายในคอนเทนเนอร์ของตน ต้นทุนการแยกวิเคราะห์เพิ่มขึ้นเชิงเส้นตามจำนวนเซลล์ และมีรอบการกำหนดขนาดคอลัมน์ที่ O(rows x cols) งบประมาณคือ wall_ms: 1500, peak_mb: 96 ควรรักษาตารางเดียวให้อยู่ภายในขอบเขตโหนดของ ADR-020 ที่ 5,000 โหนดต่อคอนเท็กซ์

ข้อความตัดตอนจากเมทริกซ์การรองรับ CSS (เฉพาะแถวที่เป็น Verified)

ข้อความตัดตอนนี้รวมเฉพาะแถวที่เป็น Verified จากเมทริกซ์การรองรับ CSS ที่ผ่านการตรวจสอบความถูกต้องแล้ว

โมดูล W3C	ระดับ	สถานะ	หลักฐาน
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/`, `tests/Unit/Html/Table/` + การทดสอบ TableParser + golden PDF
CSS Flexible Box Layout — เค้าโครงกล่องแบบยืดหยุ่น (`css_flexbox_1`)	1	Verified	`src/Html/Flex/`, `tests/Unit/Html/Flex/`
CSS Grid Layout (`css_grid_1`)	1	Verified	`src/Html/Grid/`, คอร์ปัส WPT
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

background-color ซึ่งใช้ในที่นี้สำหรับการแบ่งแถวเป็นแถบสี ได้รับการจัดระดับเป็น “Claimed” ในเมทริกซ์ ภายใต้การตรวจสอบ Phase 0 พร็อพเพอร์ตีนี้มีขอบเขตอยู่ที่เซลล์ตาราง พร็อพเพอร์ตีนี้เรนเดอร์สำหรับแถวตาราง แต่ยังไม่ได้ระบุเป็น Verified

ข้อจำกัดของการสตรีมแบบรอบเดียว (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
ในโหมด fixed เนื้อหาของเซลล์จะถูกละเว้นในการคำนวณความกว้างคอลัมน์	W3C CSS Table Level 3	css_tables_3#x1.x4.x5.x1.p6

สูตรนี้แสดงวิธีที่ NextPDF เรนเดอร์ตาราง HTML โดยมี CSS Table Level 3 ที่จัดเป็น Verified ในเมทริกซ์การรองรับ และโมดูล CSS อื่นที่ใช้ในที่นี้ก็ได้รับการจัดระดับโดยเมทริกซ์เดียวกัน

บริบทเชิงพาณิชย์

ไม่มี