Layout für eine HTML-Tabelle erstellen

Auf einen Blick

Dieses Recipe rendert eine HTML-Tabelle mit Kopfzeile, ausgerichteten Zellen, Rahmen und Fußzeile. Tabellen sind in der CSS-Support-Matrix als verifiziertes Modul geführt. Das Recipe orientiert sich an examples/09-html-table.php.

Installation

composer require nextpdf/core:^3

Dieser Constraint zielt auf das Paket nextpdf/core. Das Beispiel läuft unter PHP 8.4.

Konzeptueller Überblick

Die HTML-Engine verfügt über eine dedizierte Tabellen-Pipeline (src/Html/Table/). TableParser sammelt Zeilen und Zellen in einem kurzlebigen Puffer; anschließend wird die Tabelle gelayoutet und gezeichnet. Das ist die einzige anerkannte Abweichung vom No-retained-DOM-Modell in ADR-001. Der Puffer ist kurzlebig und auf seinen Container begrenzt. Er ist kein persistentes DOM.

Die Spaltenbreiten folgen dem CSS-Table-Modell. Die Tabelle wird bei einer vorgegebenen verwendeten Breite gelayoutet; anschließend legt der Spaltenbreiten-Algorithmus die verwendete Breite jeder Spalte fest (W3C CSS Table Level 3). Mit table-layout: fixed wird der Zelleninhalt bei der Breitenberechnung ignoriert. Stattdessen bestimmen die erste Zeile und die expliziten Spaltenbreiten das Layout (W3C CSS Table Level 3).

CSS Table Level 3 ist in der Matrix als Verified eingestuft. Diese Einstufung stützt sich auf vier Quellen: src/Html/Table/, die Table-Unit-Suite, die TableParser-Tests und synthetische Golden-PDFs.

API-Oberfläche

Tabellen werden über writeHtml(string $html): static gerendert (NextPDF\Core\Concerns\HasTextOutput). Die Engine unterstützt Standard-Tabellen-Markup. Die unterstützten Tags sind table, thead, tbody, tfoot, tr, th und td. Die unterstützten Attribute sind border, cellpadding, cellspacing, colspan und ein style pro Zelle. Die vollständige PHPDoc-Tabelle wird aus dem Quellcode generiert.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

Dieses Beispiel ist eigenständig und kann vom Harness ausgeführt werden. Es entspricht examples/09-html-table.php und zeigt eine gestylte Kopfzeile, abwechselnde Zeilenhintergründe, ausgerichtete numerische Spalten und eine Fußzeilensumme.

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

Erwartete STDOUT-Ausgabe:

Wrote html-table-layout.pdf

Grenzfälle & Stolperfallen

Prozentuale Breiten. Prozentangaben für die Spalten-width werden relativ zur verwendeten Tabellenbreite aufgelöst. Der Spaltenbreiten-Algorithmus normalisiert Prozentangaben, die zusammen nicht 100 ergeben. Gehen Sie nicht von exakten Pixelbreiten aus.
colspan. Eine Zelle, die mehrere Spalten überspannt, nimmt an der Breitenverteilung über die von ihr abgedeckten Spalten hinweg teil. Eine Fußzeilensumme, die die meisten Spalten überspannt, ist ein gängiges, unterstütztes Muster.
Rahmenmodell. In manchen Tabellen-Fixtures weicht der Standardwert von border-collapse vom CSS-Initialwert ab. Setzen Sie ihn direkt, wenn das Rahmen-Rendering relevant ist.
Rowspan über Seitenumbrüche hinweg. Eine Zelle mit Rowspan kann eine Seitengrenze überschreiten; der Rowspan-Paginator fragmentiert diese Zelle dann (ADR-007). Eine sehr hohe Zelle, die sich nicht aufteilen lässt, kann eine UnsplittableContentException auslösen.
Leere Zellen. Eine leere <td> belegt weiterhin ihren Rasterplatz. Sie wird nicht kollabiert.

Performance

Der Tabellen-Puffer ist kurzlebig und auf seinen Container begrenzt. Die Parsing-Kosten skalieren linear mit der Zellenanzahl, zuzüglich des Spaltenbreiten-Durchlaufs mit O(Zeilen x Spalten). Das Budget beträgt wall_ms: 1500, peak_mb: 96. Halten Sie eine einzelne Tabelle innerhalb der ADR-020-Knotengrenze von 5,000 Knoten pro Kontext.

Auszug aus der CSS-Support-Matrix (nur Verified-Zeilen)

Dieser Auszug gibt nur die Verified-Zeilen aus der geprüften CSS-Support-Matrix wieder.

W3C-Modul	Level	Status	Nachweis
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/`, `tests/Unit/Html/Table/` + TableParser-Tests + Golden-PDFs
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-Korpus
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

background-color, hier für das Zeilen-Striping verwendet, ist in der Matrix als „Claimed“ eingestuft. Laut Phase-0-Audit ist der Geltungsbereich die Tabellenzelle. Beim Rendern von Tabellenzeilen wird sie angewendet, ist aber nicht als Verified gelistet.

Single-Pass-Streaming-Einschränkungen (ADR-001)

Der Tabellen-Puffer ist die dokumentierte Ausnahme vom Streaming-Modell. Er ist kurzlebig und begrenzt, aber kein allgemeines DOM. Verlassen Sie sich nicht darauf, dass eine Tabelle für Inhalte außerhalb der Tabelle einen Baumkontext bereitstellt.

Layer-Verträge (ADR-010)

FormattingContextFactory::startTable() liest CSS über den Vertrag des Layout-Layers. Beim Dispatch wird kein rohes $css[...] geparst. Die öffentliche Oberfläche bleibt writeHtml().

Speicherbudget für große Dokumente

Ein Tabellen-Formatierungskontext ist auf 5,000 Knoten und 20 Ebenen Tiefe begrenzt und bleibt innerhalb der Obergrenze für aktiven Speicher von 50 MB (ADR-020). Teilen Sie eine sehr große Tabelle auf oder paginieren Sie sie. Rendern Sie sie nicht als einen einzigen überdimensionierten Kontext.

Sicherheitshinweise

Tabellen-Markup aus nicht vertrauenswürdigen Eingaben unterliegt denselben Element- und Verschachtelungsgrenzen wie anderes HTML. Validieren Sie Tabellendaten, die Benutzer zusammenstellen. Der Renderer führt keinen Inhalt aus und ruft gemäß der Standardrichtlinie keine beliebigen Remote-Ressourcen ab.

Konformität

Aussage	Spec	Klausel	reference_id
Die verwendeten Spaltenbreiten werden vom Tabellen-Spaltenbreiten-Algorithmus bei der verwendeten Tabellenbreite bestimmt.	W3C CSS Table Level 3	css_tables_3#x1.x4.x9.x3
Im Fixed-Modus wird der Zelleninhalt bei der Spaltenbreitenberechnung ignoriert.	W3C CSS Table Level 3	css_tables_3#x1.x4.x5.x1.p6

Dieses Recipe zeigt, wie NextPDF unterstützte HTML-Tabellen rendert. CSS Table Level 3 ist in der Support-Matrix als Verified eingestuft; die weiteren hier verwendeten CSS-Module sind gemäß dieser Matrix eingestuft.

Kommerzieller Kontext

Nicht zutreffend.