HTML 表格排版

概覽

本範例會繪製一個包含表頭、對齊儲存格、框線與表尾列的 HTML 表格。在 CSS 支援矩陣中，表格屬於「已驗證」的模組。本範例依循 examples/09-html-table.php。

安裝

composer require nextpdf/core:^3

此版本限制會鎖定 nextpdf/core 套件。此範例在 PHP 8.4 上執行。

概念說明

HTML 引擎具備一條專屬的表格管線（src/Html/Table/）。TableParser 會把各列與儲存格收集到一個短暫的緩衝區，接著再進行表格的排版與繪製。這是 ADR-001 中唯一被認定會偏離「不保留 DOM」模型的地方。此緩衝區生命週期短暫，並侷限於其容器範圍內。它並不是持久存在的 DOM。

欄寬遵循 CSS Table 模型。表格會依給定的使用寬度進行排版，欄寬計算演算法接著設定每一欄的使用寬度（W3C CSS Table Level 3）。在 table-layout: fixed 下，計算寬度時會忽略儲存格內容。版面改由第一列與明確指定的欄寬主導（W3C CSS Table Level 3）。

在矩陣中，CSS Table Level 3 被評定為 已驗證。這項評定由四項來源支撐：src/Html/Table/、Table 單元測試套件、TableParser 測試，以及合成黃金 PDF。

API 介面

表格是透過 writeHtml(string $html): static 繪製的（NextPDF\Core\Concerns\HasTextOutput）。此引擎支援標準表格 markup（標記語言）。支援的標籤有 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 百分比會相對於表格的使用寬度 resolve（解析）。當百分比總和不等於 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 支援矩陣摘錄（僅列出「已驗證」的列）

此摘錄只重現 已驗證 的列，這些列取自通過真實性稽核的 CSS 支援矩陣。

W3C 模組	層級	狀態	佐證
CSS Table 表格（`css_tables_3`）	3	已驗證	`src/Html/Table/`、`tests/Unit/Html/Table/`，外加 TableParser 測試與黃金 PDF
CSS Flexible Box Layout 彈性盒子版面（`css_flexbox_1`）	1	已驗證	`src/Html/Flex/`、`tests/Unit/Html/Flex/`
CSS Grid Layout 格線版面（`css_grid_1`）	1	已驗證	`src/Html/Grid/`，WPT 語料庫
CSS Cascading and Inheritance 階層與繼承（`css_cascade_3`）	3	已驗證	`src/Html/Cascade/`

background-color 在此用來產生列的條紋背景，在矩陣中被評定為「已宣稱」。依據 Phase 0 稽核，其適用範圍是表格儲存格。它對表格的列會正常繪製，但並未列為「已驗證」。

單趟串流的限制（ADR-001）

表格緩衝區是串流模型中載明的例外。其生命週期短暫且有界，並不是一般用途的 DOM。不要依賴表格替表格外部的內容提供樹狀脈絡。

分層契約（ADR-010）

FormattingContextFactory::startTable() 透過版面層契約讀取 CSS。它不會在分派過程中剖析原始的 $css[...]。對外公開的介面維持為 writeHtml()。

大型文件的記憶體預算

在 50 MB 的作用中記憶體上限內，一個表格格式化情境受限於最多 5,000 個節點與 20 層的巢狀深度（ADR-020）。對非常大的表格，請將其切分或分頁處理。不要把它繪製成單一過大的情境。

安全性注意事項

來自不可信輸入的表格標記語言會受到與其他 HTML 相同的元素與巢狀深度上限約束。請驗證使用者組裝的表格資料。renderer（渲染器）不會執行內容，且在預設政策下也不會抓取任意遠端資源。

符合性

陳述	規範	條款	參考 ID
使用欄寬由表格欄寬計算演算法在使用表格寬度下決定。	W3C CSS Table Level 3 標準	css_tables_3#x1.x4.x9.x3（條款編號）
在固定模式下，計算欄寬時會忽略儲存格內容。	W3C CSS Table Level 3 標準	css_tables_3#x1.x4.x5.x1.p6（條款編號）

本範例展示 NextPDF 如何繪製受支援的 HTML 表格。CSS Table Level 3 在支援矩陣中為「已驗證」，此處使用的其他 CSS 模組則依該矩陣評定等級。

商業脈絡

不適用。