Bố cục bảng HTML

Tổng quan nhanh

Dùng công thức này để kết xuất bảng Hypertext Markup Language (HTML) có tiêu đề, ô được căn chỉnh, đường viền và hàng chân trang. CSS Table là mô-đun được xếp hạng Verified trong ma trận hỗ trợ Cascading Style Sheets (CSS). Công thức này dựa trên examples/09-html-table.php.

Cài đặt

composer require nextpdf/core:^3

Ràng buộc này cài đặt gói nextpdf/core. Ví dụ này chạy trên PHP 8.4.

Tổng quan khái niệm

Engine HTML dùng một luồng xử lý bảng riêng (src/Html/Table/). TableParser thu thập các hàng và ô vào một vùng đệm ngắn hạn, sau đó NextPDF dàn bố cục và vẽ bảng. Đây là ngoại lệ duy nhất được ghi nhận so với mô hình không lưu giữ Document Object Model (DOM) trong ADR-001. Vùng đệm này chỉ tồn tại trong thời gian ngắn và bị giới hạn trong phạm vi vùng chứa của nó. Nó không phải là một DOM tồn tại lâu dài.

Chiều rộng cột tuân theo mô hình CSS Table. NextPDF bố trí bảng theo một chiều rộng sử dụng nhất định, rồi thuật toán định kích thước cột đặt chiều rộng sử dụng cho từng cột (W3C CSS Table Level 3). Với table-layout: fixed, nội dung ô bị bỏ qua khi tính chiều rộng. Thay vào đó, hàng đầu tiên và các chiều rộng cột được khai báo tường minh sẽ chi phối bố cục (W3C CSS Table Level 3).

CSS Table Level 3 được xếp hạng Verified trong ma trận. Xếp hạng này được củng cố bởi bốn nguồn bằng chứng: src/Html/Table/, bộ kiểm thử đơn vị Table, các bài kiểm thử TableParser, và các PDF golden tổng hợp.

Bề mặt API

Kết xuất bảng bằng writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Engine hỗ trợ cú pháp đánh dấu bảng chuẩn. Các thẻ được hỗ trợ gồm table, thead, tbody, tfoot, tr, th, và td. Các thuộc tính được hỗ trợ gồm border, cellpadding, cellspacing, colspan, cùng thuộc tính style ở cấp ô. Bảng PHPDoc đầy đủ được sinh từ mã nguồn.

Mã mẫu — khởi đầu nhanh

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

Mã mẫu — bản dùng cho sản xuất

Ví dụ độc lập này có thể chạy trong bộ kiểm thử (harness). Ví dụ bám theo examples/09-html-table.php và minh họa tiêu đề được định kiểu, các hàng có màu nền xen kẽ, các cột số được căn chỉnh, cùng một hàng tổng ở chân trang.

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

Đầu ra chuẩn (STDOUT) dự kiến:

Wrote html-table-layout.pdf

Trường hợp biên & điểm cần lưu ý

Chiều rộng theo phần trăm. Giá trị phần trăm của width cho cột được tính theo chiều rộng sử dụng của bảng. Thuật toán định kích thước cột sẽ chuẩn hóa các phần trăm có tổng khác 100. Đừng giả định chiều rộng chính xác đến từng pixel.
colspan. Một ô trải rộng được tính vào việc phân bổ chiều rộng cho các cột mà nó bao phủ. Hàng tổng ở chân trang trải rộng qua phần lớn các cột là một mẫu phổ biến và được hỗ trợ.
Mô hình đường viền. Trong một số fixture bảng, giá trị mặc định của border-collapse khác với giá trị khởi tạo của CSS. Hãy đặt trực tiếp giá trị này khi việc kết xuất đường viền là quan trọng.
Rowspan băng qua ngắt trang. Một ô có rowspan có thể vượt qua ranh giới trang, và khi đó bộ phân trang rowspan sẽ phân mảnh ô đó (ADR-007). Một ô rất cao và không thể chia tách có thể làm phát sinh UnsplittableContentException.
Ô trống. Một <td> trống vẫn chiếm vị trí tương ứng trong lưới. Nó không bị thu gọn hay loại bỏ.

Hiệu năng

Vùng đệm bảng tồn tại trong thời gian ngắn và bị giới hạn trong phạm vi vùng chứa của nó. Chi phí phân tích cú pháp tăng tuyến tính theo số lượng ô, cộng thêm bước định kích thước cột ở mức O(rows x cols). Ngân sách là wall_ms: 1500, peak_mb: 96. Hãy giữ mỗi bảng đơn lẻ trong giới hạn số nút của ADR-020 là 5,000 nút cho mỗi ngữ cảnh.

Trích đoạn ma trận hỗ trợ CSS (chỉ các hàng Verified)

Trích đoạn này chỉ bao gồm các hàng Verified từ ma trận hỗ trợ CSS đã được kiểm chứng độ chính xác.

Mô-đun W3C	Cấp	Trạng thái	Bằng chứng
CSS Table (`css_tables_3`)	3	Verified	`src/Html/Table/`, `tests/Unit/Html/Table/` + các bài kiểm thử TableParser + các 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/`, kho ngữ liệu WPT
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

background-color, được dùng ở đây để tô màu các hàng xen kẽ, được xếp hạng “Claimed” trong ma trận. Theo đợt kiểm toán Phase 0, phạm vi áp dụng của nó là ô bảng. Nó vẫn được kết xuất trên các hàng của bảng, nhưng không được liệt kê dưới dạng Verified.

Ràng buộc của luồng một lượt (ADR-001)

Vùng đệm bảng là ngoại lệ đã được ghi nhận đối với mô hình luồng. Nó tồn tại trong thời gian ngắn và có giới hạn, không phải là một DOM tổng quát. Đừng dựa vào bảng để cung cấp ngữ cảnh cây cho nội dung bên ngoài bảng.

Hợp đồng giữa các lớp (ADR-010)

FormattingContextFactory::startTable() đọc CSS thông qua hợp đồng của lớp bố cục. Nó không phân tích cú pháp $css[...] thô trong đường điều phối. API công khai vẫn là writeHtml().

Ngân sách bộ nhớ cho tài liệu lớn

Một ngữ cảnh định dạng bảng bị giới hạn ở 5,000 nút và độ sâu 20 cấp, trong giới hạn trần bộ nhớ hoạt động 50 MB (ADR-020). Hãy chia nhỏ hoặc phân trang các bảng rất lớn. Đừng kết xuất bảng đó thành một ngữ cảnh quá khổ.

Ghi chú bảo mật

Cú pháp đánh dấu bảng từ nguồn nhập không đáng tin cậy bị giới hạn bởi cùng các mức trần về số phần tử và độ lồng nhau như HTML khác. Hãy xác thực dữ liệu bảng do người dùng tạo. Bộ kết xuất không thực thi nội dung và, theo chính sách mặc định, không nạp tùy ý các tài nguyên từ xa.

Tuân thủ

Phát biểu	Đặc tả	Điều khoản	reference_id
Chiều rộng sử dụng của các cột được xác định bởi thuật toán định kích thước cột của bảng tại chiều rộng sử dụng của bảng.	W3C CSS Table Level 3	css_tables_3#x1.x4.x9.x3
Ở chế độ fixed, nội dung ô bị bỏ qua khi tính chiều rộng cột.	W3C CSS Table Level 3	css_tables_3#x1.x4.x5.x1.p6

Công thức này minh họa cách NextPDF kết xuất các bảng HTML được hỗ trợ. CSS Table Level 3 được xếp hạng Verified trong ma trận hỗ trợ, và các mô-đun CSS khác được dùng ở đây cũng có xếp hạng trong cùng ma trận.

Bối cảnh thương mại

Không áp dụng.