Menata tabel HTML

Sekilas pandang

Gunakan resep ini untuk merender tabel Hypertext Markup Language (HTML) dengan header, sel yang terselaraskan, garis tepi, dan baris footer. Modul Table berstatus Verified dalam matriks dukungan CSS (Cascading Style Sheets). Resep ini mengikuti examples/09-html-table.php.

Instalasi

composer require nextpdf/core:^3

Perintah ini memasang paket nextpdf/core. Contoh ini berjalan pada PHP 8.4.

Gambaran konseptual

Mesin HTML menggunakan alur tabel khusus (src/Html/Table/). TableParser mengumpulkan baris dan sel ke dalam buffer berumur pendek, lalu NextPDF menata dan menggambar tabel. Ini merupakan satu-satunya penyimpangan yang diakui dari model tanpa retensi Document Object Model (DOM) di ADR-001. Buffer ini berumur pendek dan cakupannya terbatas pada kontainernya. Ini bukan DOM yang persisten.

Lebar kolom mengikuti model CSS Table. NextPDF menata tabel pada lebar terpakai tertentu, lalu algoritma penentuan ukuran kolom menetapkan lebar terpakai setiap kolom (W3C CSS Table Level 3). Dengan table-layout: fixed, konten sel diabaikan dalam penghitungan lebar. Sebagai gantinya, baris pertama dan lebar kolom eksplisitlah yang menentukan tata letak (W3C CSS Table Level 3).

CSS Table Level 3 dinilai Verified dalam matriks. Empat sumber menjadi dasar penilaian ini: src/Html/Table/, suite unit Table, pengujian TableParser, dan PDF golden sintetis.

Permukaan API

Render tabel menggunakan writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Mesin ini mendukung markup tabel standar. Tag yang didukung adalah table, thead, tbody, tfoot, tr, th, dan td. Atribut yang didukung adalah border, cellpadding, cellspacing, colspan, dan atribut style per sel. Tabel PHPDoc lengkap dihasilkan dari kode sumber.

Contoh kode — Mulai cepat

<?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');

Contoh kode — Produksi

Contoh mandiri ini dapat dijalankan di dalam harness. Contoh ini mencerminkan examples/09-html-table.php dan menampilkan header bergaya, latar baris berselang-seling, kolom numerik yang terselaraskan, dan total di baris footer.

<?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";

Keluaran standar yang diharapkan (STDOUT):

Wrote html-table-layout.pdf

Kasus tepi & jebakan

Lebar dalam persentase. Persentase width kolom dihitung relatif terhadap lebar tabel terpakai. Algoritma penentuan ukuran kolom menormalkan persentase yang totalnya tidak mencapai 100. Jangan berasumsi lebar pikselnya akan persis.
colspan. Sel yang membentang ikut serta dalam distribusi lebar di seluruh kolom yang dicakupnya. Total di footer yang membentang ke sebagian besar kolom adalah pola umum yang didukung.
Model garis tepi. Pada beberapa fixture tabel, nilai standar border-collapse berbeda dari nilai awal CSS. Setel nilainya secara eksplisit jika hasil render garis tepi penting.
Rowspan yang melintasi pemisah halaman. Sel dengan rowspan dapat melintasi batas halaman, lalu paginator rowspan memecah sel tersebut (ADR-007). Sel yang sangat tinggi dan tidak dapat dipecah dapat memunculkan UnsplittableContentException.
Sel kosong. <td> yang kosong tetap menempati slot grid-nya. Sel tersebut tidak dihilangkan.

Performa

Buffer tabel berumur pendek dan cakupannya terbatas pada kontainernya. Biaya parsing linear terhadap jumlah sel, ditambah tahap penentuan ukuran kolom sebesar O(rows x cols). Anggarannya adalah wall_ms: 1500, peak_mb: 96. Jaga agar satu tabel tetap dalam batas node ADR-020 sebesar 5,000 node per konteks.

Kutipan matriks dukungan CSS (hanya baris Verified)

Kutipan ini hanya mencakup baris Verified dari matriks dukungan CSS yang telah diaudit kebenarannya.

Modul W3C	Level	Status	Bukti
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/`, `tests/Unit/Html/Table/` + pengujian TableParser + PDF golden
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/`, korpus WPT
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

background-color, yang dipakai di sini untuk striping baris, dinilai “Claimed” dalam matriks. Berdasarkan audit Phase 0, cakupannya adalah sel tabel. Properti ini dirender untuk baris tabel, tetapi tidak tercantum sebagai Verified.

Batasan streaming sekali jalan (ADR-001)

Buffer tabel adalah pengecualian yang terdokumentasi terhadap model streaming. Buffer ini berumur pendek dan terbatas, bukan DOM umum. Jangan mengandalkan tabel untuk menyediakan konteks pohon bagi konten di luar tabel.

Kontrak lapisan (ADR-010)

FormattingContextFactory::startTable() membaca CSS melalui kontrak lapisan tata letak. Metode ini tidak mem-parsing $css[...] mentah di jalur dispatch. Permukaan publiknya tetap writeHtml().

Anggaran memori untuk dokumen besar

Konteks pemformatan tabel dibatasi hingga 5,000 node dan 20 tingkat kedalaman, dalam batas atas memori aktif 50 MB (ADR-020). Pecah atau paginasi tabel yang sangat besar. Jangan merendernya sebagai satu konteks yang berukuran berlebihan.

Catatan keamanan

Markup tabel dari input yang tidak tepercaya dibatasi oleh batas elemen dan penyarangan yang sama seperti HTML lainnya. Validasi data tabel yang dirakit oleh pengguna. Renderer tidak mengeksekusi konten, dan di bawah kebijakan standar, renderer tidak mengambil sumber daya jarak jauh secara sembarang.

Konformansi

Pernyataan	Spesifikasi	Klausa	reference_id
Lebar kolom terpakai ditentukan oleh algoritma penentuan ukuran kolom tabel pada lebar tabel terpakai.	W3C CSS Table Level 3	css_tables_3#x1.x4.x9.x3
Dalam mode fixed, konten sel diabaikan dalam penghitungan lebar kolom.	W3C CSS Table Level 3	css_tables_3#x1.x4.x5.x1.p6

Resep ini menunjukkan cara NextPDF merender tabel HTML yang didukung. CSS Table Level 3 berstatus Verified dalam matriks dukungan, dan modul CSS lain yang dipakai di sini dinilai oleh matriks tersebut.

Konteks komersial

Tidak berlaku.