Een HTML-tabel opmaken

In een oogopslag

Gebruik dit recipe om een Hypertext Markup Language (HTML)-tabel te renderen met een tabelkop, uitgelijnde cellen, randen en een voettekstrij. Tabellen zijn een Verified-module in de ondersteuningsmatrix voor Cascading Style Sheets (CSS). Het recipe volgt examples/09-html-table.php.

Installatie

composer require nextpdf/core:^3

Met deze constraint installeer je het pakket nextpdf/core. Het voorbeeld draait op PHP 8.4.

Conceptueel overzicht

De HTML-engine gebruikt een speciale tabelpijplijn (src/Html/Table/). TableParser verzamelt rijen en cellen in een kortlevende buffer, waarna NextPDF de tabel opmaakt en tekent. Dit is de enige erkende afwijking van het model zonder bewaard Document Object Model (DOM) in ADR-001. De buffer is kortlevend en beperkt tot de bijbehorende container. Dit is geen permanente DOM.

Kolombreedtes volgen het CSS Table-model. NextPDF maakt de tabel op met een bepaalde gebruikte breedte, waarna het kolomgrootte-algoritme de gebruikte breedte van elke kolom bepaalt (W3C CSS Table Level 3). Met table-layout: fixed wordt celinhoud genegeerd bij de breedteberekening. In plaats daarvan bepalen de eerste rij en de expliciete kolombreedtes de lay-out (W3C CSS Table Level 3).

CSS Table Level 3 krijgt in de matrix de beoordeling Verified. Vier bronnen onderbouwen die beoordeling: src/Html/Table/, de Table-unitsuite, de TableParser-tests en synthetische golden-PDF’s.

API-oppervlak

Render tabellen met writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). De engine ondersteunt standaard tabelmarkup. Ondersteunde tags zijn table, thead, tbody, tfoot, tr, th en td. Ondersteunde attributen zijn border, cellpadding, cellspacing, colspan en een style per cel. De volledige PHPDoc-tabel komt uit de broncode.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

Dit op zichzelf staande voorbeeld kan in het testharnas draaien. Het komt overeen met examples/09-html-table.php en toont een opgemaakte tabelkop, afwisselende rijachtergronden, uitgelijnde numerieke kolommen en een totaal in de voettekst.

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

Verwachte standaarduitvoer (STDOUT):

Wrote html-table-layout.pdf

Randgevallen en valkuilen

Procentuele breedtes. Percentagewaarden voor kolom-width worden berekend ten opzichte van de gebruikte tabelbreedte. Het kolomgrootte-algoritme normaliseert percentages die niet optellen tot 100. Ga niet uit van exacte pixelbreedtes.
colspan. Een overspannende cel neemt deel aan de breedteverdeling over de kolommen die hij beslaat. Een voetteksttotaal dat de meeste kolommen overspant, is een veelvoorkomend, ondersteund patroon.
Randmodel. In sommige tabelfixtures wijkt de standaardwaarde van border-collapse af van de initiële CSS-waarde. Stel deze rechtstreeks in wanneer de weergave van randen belangrijk is.
Rowspan over pagina-einden heen. Een cel met rowspan kan over een paginagrens lopen, waarna de rowspan-paginator die cel fragmenteert (ADR-007). Een zeer hoge cel die niet kan worden opgesplitst, kan UnsplittableContentException veroorzaken.
Lege cellen. Een lege <td> blijft zijn rasterpositie innemen. De cel wordt niet weggewerkt.

Prestaties

De tabelbuffer is kortlevend en beperkt tot de bijbehorende container. De parseerkosten zijn lineair in het aantal cellen, plus de kolomgroottebepaling met O(rows x cols). Het budget is wall_ms: 1500, peak_mb: 96. Houd één tabel binnen de ADR-020-knooppuntgrens van 5,000 knooppunten per context.

Fragment uit de CSS-ondersteuningsmatrix (alleen Verified-rijen)

Dit fragment bevat alleen de Verified-rijen uit de feitengecontroleerde CSS-ondersteuningsmatrix.

W3C-module	Niveau	Status	Bewijs
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/`, `tests/Unit/Html/Table/` + TableParser-tests + golden-PDF’s
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-corpus
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

background-color, hier gebruikt voor afwisselende rijkleuring, krijgt in de matrix de beoordeling „Claimed”. In de Phase 0-audit is het bereik de tabelcel. Het wordt voor tabelrijen gerenderd, maar staat niet vermeld als Verified.

Beperkingen van single-pass streaming (ADR-001)

De tabelbuffer is de gedocumenteerde uitzondering op het streamingmodel. Hij is kortlevend en begrensd, geen algemene DOM. Vertrouw er niet op dat een tabel boomcontext biedt voor inhoud buiten die tabel.

Laagcontracten (ADR-010)

FormattingContextFactory::startTable() leest CSS via het contract van de lay-outlaag. Het parseert geen ruwe $css[...] in het dispatchpad. Het publieke oppervlak blijft writeHtml().

Geheugenbudget voor grote documenten

Een tabelopmaakcontext is begrensd tot 5,000 knooppunten en 20 niveaus diep, binnen het plafond van 50 MB actief geheugen (ADR-020). Splits een zeer grote tabel of verdeel deze over pagina’s. Render hem niet als één te grote context.

Beveiligingsnotities

Tabelmarkup uit niet-vertrouwde invoer wordt begrensd door dezelfde element- en nestingslimieten als andere HTML. Valideer tabelgegevens die een gebruiker samenstelt. De renderer voert geen inhoud uit en haalt met het standaardbeleid geen willekeurige externe bronnen op.

Conformiteit

Verklaring	Specificatie	Clausule	reference_id
De gebruikte kolombreedtes worden bepaald door het kolomgrootte-algoritme van de tabel bij de gebruikte tabelbreedte.	W3C CSS Table Level 3	css_tables_3#x1.x4.x9.x3
In de vaste modus wordt celinhoud genegeerd bij de berekening van de kolombreedte.	W3C CSS Table Level 3	css_tables_3#x1.x4.x5.x1.p6

Dit recipe laat zien hoe NextPDF ondersteunde HTML-tabellen rendert. CSS Table Level 3 is Verified in de ondersteuningsmatrix, en de overige hier gebruikte CSS-modules worden door die matrix beoordeeld.

Commerciële context

Niet van toepassing.