HTML: hệ thống con kết xuất HTML+CSS sang PDF

Tổng quan nhanh

Hệ thống con HTML chuyển HyperText Markup Language (HTML) và Cascading Style Sheets (CSS) thành các luồng nội dung Portable Document Format (PDF) trong một lượt tiến về trước. Đây là hệ thống con lớn nhất và có rủi ro cao nhất của engine, gồm 324 tệp trong src/Html/.

Cài đặt

composer require nextpdf/core:^3

Tổng quan khái niệm

Hệ thống con HTML là bộ kết xuất luồng một lượt từ HTML+CSS sang PDF. Bề mặt công khai của nó là một phương thức: Document::writeHtml(). Bên trong, HtmlParser tách đầu vào thành token, phân giải kiểu, tính toán bố cục và phát các toán tử PDF trong một lượt tiến về trước, không giữ lại cây tài liệu.

Cần làm rõ phạm vi. Hệ thống con này không phải là bộ kết xuất giữ lại tài liệu. Nó không giữ đồ thị phần tử, không bố cục lại nội dung đã ghi, cũng không cho phép đầu vào thay đổi sau khi quá trình phân tích bắt đầu. Nó hiện thực một tập con CSS được tuyển chọn theo các đặc tả được ghim cố định. Hai Architecture Decision Record (ADR) chi phối hệ thống con này. ADR-001 định nghĩa mô hình luồng một lượt và các giới hạn của mô hình đó. ADR-010 định nghĩa hợp đồng bốn tầng (phân tích CSS, trạng thái kiểu, bố cục, vẽ), cùng với các phần bổ trợ về phương tiện phân trang và đo lường.

HtmlParser được xếp loại rủi ro nghiêm trọng trong manifest của mô-đun. Có năm tệp được ghi nhận với chú thích vùng nguy hiểm: bộ điều phối HtmlParser (bộ tách token theo luồng, hơn 1.000 dòng mã (LOC)), HtmlStyleState (hơn 100 trường thuộc tính CSS với mô hình kế thừa theo ngăn xếp), HtmlBlockHandler (điều phối khối gắn chặt với trạng thái kiểu), FlexLayoutEngine (đo lường và bố cục flex đầy đủ), và TableParser (phân trang colspan/rowspan qua các điểm ngắt trang). Hãy xem các thay đổi ở đây là công việc cần thực hiện trong chế độ lập kế hoạch.

Hãy dùng trang này làm điểm khởi đầu. Xem pipeline để biết trình tự các giai đoạn, css-resolver để tìm hiểu cascade và độ đặc hiệu, layer-contracts-adr010 để nắm ranh giới giữa các tầng, và streaming-constraints-adr001 để hiểu mô hình không giữ cây cùng các giới hạn của nó.

Văn bản phải-sang-trái và hai chiều

writeHtml() kết xuất nội dung phải-sang-trái (RTL). Hãy đặt thuộc tính CSS direction: rtl trên body, một bảng hoặc bất kỳ phần tử nào. Engine phân giải thứ tự hiển thị bằng Unicode Bidirectional Algorithm (UAX #9) thông qua bộ máy hai chiều của tầng typography — xem Typography để biết chi tiết về BidiEngine. Nội dung trộn lẫn Latinh, tiếng Ả Rập và chữ số được sắp xếp đúng, và một con số đứng sau tiếng Ả Rập vẫn giữ các chữ số của nó theo trái-sang-phải.

Tiếng Ả Rập còn được tạo hình theo ngữ cảnh: engine chọn dạng đầu, giữa, cuối hoặc tách rời của từng chữ cái và áp dụng chữ ghép Lam-Alef. Việc tạo hình cần một phông chữ đã đăng ký có bản đồ ký tự bao phủ khối Arabic Presentation Forms-B; một face chỉ có Latinh, kể cả các phông chữ standard-14, không thể vẽ tiếng Ả Rập. Trong các bảng, mỗi ô được sắp xếp lại và tạo hình riêng và căn về cạnh bắt đầu (phải) dưới direction: rtl. RTL áp dụng cho tiếng Ả Rập, tiếng Hebrew, tiếng Ba Tư và tiếng Urdu; tiếng Hebrew được sắp xếp lại nhưng không được tạo hình.

Hãy đặt hướng bằng thuộc tính CSS direction — thuộc tính HTML dir không ánh xạ tới nó. Việc căn chỉnh ngang của văn bản khối ngoài bảng và văn bản nội tuyến, cùng với text-align: justify, chưa được áp dụng. Để xem một hóa đơn tiếng Ả Rập có thể chạy được và danh sách đầy đủ các giới hạn hiện tại, xem Kết xuất HTML tiếng Ả Rập phải-sang-trái.

Bề mặt API

Ký hiệu	Vị trí	Vai trò
`Document::writeHtml(string $html): static`	`src/Core/Concerns/HasTextOutput.php`	Điểm truy cập công khai. Kết xuất HTML tại con trỏ hiện tại.
`Document::createStandalone(): self`	`src/Core/Document.php`	Tạo một tài liệu độc lập.
`HtmlParser::parse(string $html): HtmlRenderResult`	`src/Html/HtmlParser.php`	Bộ điều phối nội bộ.
`HtmlRenderResult`	`src/Html/HtmlRenderResult.php`	Kết quả bất biến: luồng, con trỏ kết thúc và các phông chữ đã dùng.
`DefaultHtmlSecurityPolicy`	`src/Html/DefaultHtmlSecurityPolicy.php`	Chính sách mặc định cho thẻ, thuộc tính, CSS và Uniform Resource Locator (URL).
`HtmlSecurityPolicyInterface`	`src/Contracts/HtmlSecurityPolicyInterface.php`	Hợp đồng chính sách cho các chính sách tùy chỉnh.

Mẫu mã — bắt đầu nhanh

Nguồn: examples/08-html-basic.php.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Basic');
$doc->addPage();
$doc->writeHtml('<h1 style="color:#1E3A8A;">HTML Rendering</h1><p>Direct to PDF.</p>');
$doc->save(__DIR__ . '/output/08-html-basic.pdf');

Mẫu mã — môi trường thực tế

Mẫu này minh họa một báo cáo dạng bảng có khối kiểu nhúng, dựa theo examples/09-html-table.php.

<?php

declare(strict_types=1);

require_once __DIR__ . '/../vendor/autoload.php';

use NextPDF\Core\Document;
use NextPDF\Exception\HtmlParsingException;

function renderInventory(string $rowsHtml, string $out): void
{
    $doc = Document::createStandalone();
    $doc->setTitle('Inventory');
    $doc->addPage();

    $html = '<style>table { width: 100%; } '
          . 'th { background-color: #1E3A8A; color: #FFFFFF; }</style>'
          . '<table border="1" cellpadding="5">' . $rowsHtml . '</table>';

    try {
        $doc->writeHtml($html);
    } catch (HtmlParsingException $e) {
        // Input cap, element cap (50,000), or nesting cap (100). Do not retry.
        throw $e;
    }

    $doc->save($out);
}

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

Tập con CSS được tuyển chọn. Mức hỗ trợ được ghim theo từng mô-đun. Hãy kiểm tra ma trận hỗ trợ CSS trước khi dựa vào một thuộc tính.
Các giới hạn cứng ném ngoại lệ. Các giới hạn về đầu vào 10 MB, 50,000 phần tử và 100 mức lồng nhau đều ném HtmlParsingException. Xem các ràng buộc của luồng.
Không bố cục lại. Bộ kết xuất ghi kết quả một lần theo thứ tự tài liệu; các kiểu xuất hiện muộn không thể thay đổi kết quả đã xuất trước đó.
:has() bị chặn sau cờ tính năng thử nghiệm css.has.
Hệ thống con rủi ro nghiêm trọng. Năm tệp được đánh dấu là vùng nguy hiểm. Hãy dùng chế độ lập kế hoạch cho mọi thay đổi trong src/Html/.

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

Bộ kết xuất không giữ cây tài liệu và chạy trong một lượt tiến về trước. Các giới hạn về phần tử, mức lồng nhau và đầu vào là những giới hạn cứng. Để biết đầy đủ chi tiết và hợp đồng an toàn cho worker, xem các ràng buộc của luồng (ADR-001).

Hợp đồng tầng (ADR-010)

Phân tích CSS, trạng thái kiểu, bố cục và vẽ được tách thành bốn tầng với các hợp đồng một chiều, cùng với các phần bổ trợ về phương tiện phân trang và đo lường. Để biết đầy đủ chi tiết, xem hợp đồng tầng (ADR-010).

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

Bộ nhớ dành cho trạng thái kiểu và con trỏ là O(độ sâu lồng nhau), không phải O(số lượng phần tử). performance_budget trên mỗi trang là peak_mb: 64. Giới hạn 50,000 phần tử là trần cứng; hãy chia các đầu vào lớn hơn thành nhiều lệnh gọi writeHtml(). Để biết chi tiết, xem các ràng buộc của luồng.

Hiệu năng

Quá trình duyệt là O(số lượng token). Việc xác định kích thước cột bảng thêm một lần quét hàng có giới hạn cho mỗi bảng. Lượt quét trước tùy chọn cho :has() thêm một lượt đi qua danh sách token có giới hạn. Bài benchmark hiệu năng cho pipeline kết xuất HTML áp dụng cổng kiểm soát hồi quy 5% (công việc đã hợp nhất, pull request (PR) #564). performance_budget trên mỗi trang (wall_ms: 1500, peak_mb: 64) là trần vận hành.

Ghi chú bảo mật

DefaultHtmlSecurityPolicy thực thi danh sách cho phép gồm các thẻ, thuộc tính, thuộc tính CSS và lược đồ URL, cùng với trần đầu vào 10 MB và trần lồng nhau 100 mức, độc lập với bộ phân tích. Danh sách cho phép thuộc tính CSS là trần bảo mật. Bảng hỗ trợ thời gian chạy là trần năng lực riêng biệt. Hãy hiện thực HtmlSecurityPolicyInterface để cung cấp một chính sách nghiêm ngặt hơn. DefaultExternalResourcePolicy quản lý riêng việc tải tài nguyên bên ngoài.

Trong các giá trị href và src của hình ảnh, danh sách cho phép URL cũng từ chối các đường dẫn bắt đầu bằng dấu gạch chéo ngược (\…) và các đường dẫn Universal Naming Convention (UNC) (\\host\share), bên cạnh việc từ chối đường dẫn tương đối theo giao thức (//) hiện có và danh sách cho phép chỉ-http(s)-hoặc-tương-đối. Dấu gạch chéo ngược được chuẩn hóa thành dấu gạch chéo xuôi trước khi kiểm tra, nên yêu cầu nhúng tệp cục bộ theo đường dẫn tuyệt đối của Windows hoặc tải từ share Server Message Block (SMB) không thể lọt qua nhánh “không có lược đồ, nên là tương đối”. Cả hai đường dẫn đều không mang lược đồ Uniform Resource Identifier (URI).

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

Trang này không trình bày lại mức hỗ trợ theo từng thuộc tính. Ma trận hỗ trợ CSS là nguồn thẩm quyền duy nhất về trạng thái mô-đun đã xác minh theo từng World Wide Web Consortium (W3C), bao gồm mô-đun nào là Đã xác minh và mô-đun nào là Được tuyên bố.

Tuân thủ

Hệ thống con hiện thực một tập con CSS được tuyển chọn theo các đặc tả được ghim cố định. Các ánh xạ đặc tả hành vi cho cascade được ghi nhận cùng với mã định danh điều khoản và đoạn trên css-resolver. Trạng thái tuân thủ theo từng mô-đun được trình bày trong ma trận hỗ trợ CSS.

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

Năng lực doanh nghiệp. Premium mở rộng phạm vi CSS (in ấn nâng cao và các mô-đun bổ sung) trên cùng một pipeline luồng một lượt. Kiến trúc, các giới hạn và hợp đồng tầng vẫn giữ nguyên giữa các phiên bản. Xem ma trận hỗ trợ CSS.