Układ tabeli HTML

W skrócie

Skorzystaj z tego przepisu, aby wyrenderować tabelę HTML (Hypertext Markup Language) z nagłówkiem, wyrównanymi komórkami, obramowaniami i wierszem stopki. Obsługa tabel ma w macierzy obsługi CSS (Cascading Style Sheets) status Verified. Przepis jest zgodny z examples/09-html-table.php.

Instalacja

composer require nextpdf/core:^3

To ograniczenie wersji instaluje pakiet nextpdf/core. Przykład działa na PHP 8.4.

Przegląd koncepcyjny

Silnik HTML korzysta z dedykowanego potoku tabel (src/Html/Table/). TableParser zbiera wiersze i komórki w krótkotrwałym buforze, po czym NextPDF rozkłada i rysuje tabelę. Jest to jedyne uznane odstępstwo od opisanego w ADR-001 modelu bez trwałego Document Object Model (DOM). Bufor jest krótkotrwały i ograniczony do własnego kontenera. Nie jest trwałym DOM.

Szerokości kolumn są zgodne z modelem CSS Table. NextPDF rozkłada tabelę przy zadanej używanej szerokości, a następnie algorytm doboru rozmiaru kolumn ustala używaną szerokość każdej kolumny (W3C CSS Table Level 3). W trybie table-layout: fixed zawartość komórek jest ignorowana podczas obliczania szerokości. O układzie decydują wtedy pierwszy wiersz i jawne szerokości kolumn (W3C CSS Table Level 3).

CSS Table Level 3 ma w macierzy ocenę Verified. Potwierdzają ją cztery źródła: src/Html/Table/, zestaw testów jednostkowych Table, testy TableParser oraz syntetyczne wzorcowe pliki PDF.

Powierzchnia API

Renderuj tabele za pomocą writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Silnik obsługuje standardowe znaczniki tabeli. Obsługiwane znaczniki to table, thead, tbody, tfoot, tr, th oraz td. Obsługiwane atrybuty to border, cellpadding, cellspacing, colspan oraz atrybut style definiowany na poziomie komórki. Pełna tabela PHPDoc powstaje na podstawie źródła.

Przykład kodu — szybki start

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

Przykład kodu — wersja produkcyjna

Ten samodzielny przykład nadaje się do uruchomienia w środowisku testowym. Jest zgodny z examples/09-html-table.php i pokazuje stylizowany nagłówek, naprzemienne tła wierszy, wyrównane kolumny liczbowe oraz sumę w stopce.

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

Oczekiwane wyjście standardowe (STDOUT):

Wrote html-table-layout.pdf

Przypadki brzegowe i pułapki

Szerokości procentowe. Procentowe wartości atrybutu width dla kolumn są obliczane względem używanej szerokości tabeli. Algorytm doboru rozmiaru kolumn normalizuje wartości procentowe, które nie sumują się do 100. Nie zakładaj dokładnych szerokości w pikselach.
colspan. Komórka obejmująca kilka kolumn uczestniczy w rozdziale szerokości pomiędzy obejmowane kolumny. Suma w stopce, która obejmuje większość kolumn, to częsty, obsługiwany wzorzec.
Model obramowań. W niektórych zestawach testowych dla tabel domyślna wartość border-collapse różni się od początkowej wartości CSS. Ustaw ją jawnie, gdy renderowanie obramowań ma znaczenie.
Rowspan przez podziały stron. Komórka obejmująca kilka wierszy może przejść przez granicę strony; wtedy paginator rowspan dzieli tę komórkę na fragmenty (ADR-007). Bardzo wysoka komórka, której nie można podzielić, może spowodować zgłoszenie UnsplittableContentException.
Puste komórki. Pusty <td> nadal zajmuje miejsce w siatce. Nie zostaje zwinięty.

Wydajność

Bufor tabeli jest krótkotrwały i ograniczony do własnego kontenera. Koszt parsowania rośnie liniowo wraz z liczbą komórek, z dodatkowym przebiegiem doboru rozmiaru kolumn o złożoności O(rows x cols). Budżet wynosi wall_ms: 1500, peak_mb: 96. Pilnuj, aby pojedyncza tabela mieściła się w limicie ADR-020 wynoszącym 5,000 węzłów na kontekst.

Fragment macierzy obsługi CSS (tylko wiersze Verified)

Ten fragment zawiera wyłącznie wiersze Verified z macierzy obsługi CSS audytowanej pod kątem prawdziwości.

Moduł W3C	Poziom	Status	Dowody
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/`, `tests/Unit/Html/Table/` + testy TableParser + wzorcowe pliki 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/`, korpus WPT
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

Właściwość background-color, użyta tutaj do naprzemiennego cieniowania wierszy, ma w macierzy ocenę „Claimed”. Według audytu Phase 0 jej zakres obejmuje komórkę tabeli. Renderuje się dla wierszy tabeli, ale nie jest oznaczona jako Verified.

Ograniczenia strumieniowania jednoprzebiegowego (ADR-001)

Bufor tabeli jest udokumentowanym wyjątkiem od modelu strumieniowego. Jest krótkotrwały i ograniczony; nie jest ogólnym DOM. Nie traktuj tabeli jako źródła kontekstu drzewa dla treści poza tabelą.

Kontrakty warstw (ADR-010)

FormattingContextFactory::startTable() odczytuje CSS przez kontrakt warstwy układu. Nie parsuje surowego $css[...] w ścieżce dyspozytora. Publiczną powierzchnią API pozostaje writeHtml().

Budżet pamięci dla dużych dokumentów

Kontekst formatowania tabeli jest ograniczony do 5,000 węzłów i 20 poziomów głębokości w ramach pułapu aktywnej pamięci 50 MB (ADR-020). Bardzo dużą tabelę podziel albo stronicuj. Nie renderuj jej jako jednego nadmiernie rozbudowanego kontekstu.

Uwagi dotyczące bezpieczeństwa

Znaczniki tabel pochodzące z niezaufanych danych podlegają tym samym limitom elementów i zagnieżdżenia co pozostały kod HTML. Waliduj dane tabeli przesyłane przez użytkownika. Mechanizm renderujący nie wykonuje treści i przy domyślnej polityce nie pobiera dowolnych zdalnych zasobów.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Używane szerokości kolumn są ustalane przez algorytm doboru rozmiaru kolumn tabeli dla używanej szerokości tabeli.	W3C CSS Table Level 3	css_tables_3#x1.x4.x9.x3
W trybie fixed zawartość komórek jest ignorowana podczas obliczania szerokości kolumn.	W3C CSS Table Level 3	css_tables_3#x1.x4.x5.x1.p6

Ten przepis pokazuje, jak NextPDF renderuje obsługiwane tabele HTML. CSS Table Level 3 ma w macierzy obsługi status Verified, a pozostałe użyte tutaj moduły CSS są oceniane w tej samej macierzy.

Kontekst komercyjny

Nie dotyczy.