Quy trình HTML

Spec: CSS Cascade 5, §6.1 Spec: CSS Display 3, §2 Evidence: Code-backed

Tổng quan nhanh

NextPDF kết xuất HTML và CSS thành PDF ngay trong tiến trình PHP của bạn: không cần trình duyệt, và mặc định không có tiến trình con. Trang này giải thích các giai đoạn phân lớp của quá trình chuyển đổi, phạm vi thực sự mà công cụ CSS bao quát, và khi nào ủy thác cho một trình kết xuất trình duyệt thật mới là lựa chọn trung thực.

Vì sao điều này quan trọng

“HTML thành PDF” nghe như một thao tác duy nhất. Thực ra, đó là một cascade, một mô hình hộp, một lượt bố cục và một lượt vẽ. Mỗi phần là một bài toán được đặc tả rõ ràng, với những kiểu lỗi riêng. Một công cụ gộp tất cả vào một thủ tục duy nhất sẽ dễ vỡ. Một thay đổi trong cách phân tích màu có thể làm dịch chuyển một hộp, và cách duy nhất để biết là kết xuất rồi quan sát kết quả.

Mô hình chạy trong tiến trình có một lợi thế thực tế: không phải cài trình duyệt, không phải vận hành sandbox, và không có ranh giới tiến trình để truyền dữ liệu qua lại. Nhưng lợi thế đó chỉ có giá trị nếu quá trình chuyển đổi được phân tách đủ rõ để kiểm thử riêng từng mối quan tâm. Chính kiến trúc mới là thứ khiến việc “kết xuất HTML trong PHP” trở nên đáng tin cậy, chứ không chỉ khả thi.

Tóm tắt nhanh

Việc chuyển đổi HTML/CSS chạy trong tiến trình qua writeHtml(). Kết quả là nội dung PDF gốc, không phải ảnh chụp của một trang.
Nó hoạt động một lượt và theo luồng. Bộ tách token tạo ra một danh sách token. Bộ phân tích xử lý danh sách đó từ trái sang phải, và không giữ lại cây DOM đầy đủ nào (ADR-001). Các giới hạn cứng khống chế số lượng phần tử và độ sâu lồng nhau.
Công cụ được tổ chức thành các lớp tường minh: phân tích CSS và các applicator, trạng thái kiểu, bố cục và định dạng, vẽ, và phương tiện phân trang — với những quy tắc nghiêm ngặt về trách nhiệm của từng lớp (ADR-010).
Công cụ CSS bao quát cascade, mô hình hộp và các bố cục phổ biến (block, inline, bảng, float, và nhiều hơn nữa) — phạm vi đáng kể, nhưng vẫn là một tập con xác định của những gì trình duyệt hiện đại triển khai.
Khi bạn cần độ trung thực đúng như trình duyệt cho CSS hiện đại tùy ý, NextPDF có thể ủy thác cho một trình kết xuất trình duyệt headless thông qua một phần mở rộng tùy chọn — một điểm nối có chủ đích, được cách ly khỏi mạng, không phải đường mặc định.

Cách NextPDF tiếp cận vấn đề

Quá trình chuyển đổi là một chuỗi các giai đoạn; mỗi giai đoạn nhận đầu ra đã định kiểu của giai đoạn trước.

Tokenize HTML becomes an ordered token list — no retained DOM tree.
Resolve CSS Parse styles; the cascade and applicators compute typed values.
Style state A push/pop style stack carries computed values per nesting level.
Layout Block, inline, table, and float geometry computed; no paint here.
Paint Borders, backgrounds, text, and decorations emit PDF operators.
Paged media Page-break and @page rules applied as the cursor crosses page bounds.

Quy trình xử lý HTML trong tiến trình: một lượt duy nhất từ trái sang phải trên một luồng token, với việc giải quyết CSS, trạng thái kiểu, bố cục và vẽ là các lớp riêng biệt, cùng các ngắt phương tiện phân trang được áp dụng khi con trỏ tiến tới.

Hai quy tắc kiến trúc khiến quy trình này không chỉ đơn thuần là một luồng.

Các lớp có hợp đồng. Văn bản CSS chỉ được đọc bên trong các lớp applicator. Mã bố cục tính toán hình học nhưng không phát ra toán tử vẽ nào. Mã vẽ đọc một ảnh chụp computed-style bất biến, không bao giờ đọc trạng thái theo dõi bố cục có thể thay đổi. Mã phương tiện phân trang kích hoạt các ngắt nhưng ủy thác việc trang trí trang cho lớp vẽ. Những ranh giới này được thực thi (ADR-010). Vì vậy, một thuộc tính CSS mới sẽ là một applicator mới, thay vì một thay đổi lan qua bộ phân tích, bộ điều phối bố cục và bộ vẽ cùng lúc.

Không có DOM. Việc quy trình này chạy một lượt và theo luồng là một quyết định có chủ đích (ADR-001): nhiều nhất một trạng thái kiểu cho mỗi cấp lồng nhau cộng với con trỏ đang hoạt động, chứ không phải một đối tượng cho mỗi phần tử. Một vài thao tác thực sự cần nhìn trước — định kích thước cột bảng, :has(), :last-child. Những thao tác này được xử lý bằng các cấu trúc chỉ mục quét trước, có giới hạn, trên danh sách token phẳng, chứ không bằng cách giữ lại một cây. Số lượng phần tử và độ sâu lồng nhau bị giới hạn cứng, nên đầu vào bất thường sẽ thất bại nhanh thay vì làm cạn kiệt bộ nhớ.

Công cụ CSS xử lý ngữ nghĩa CSS thật sự, không phải một bản mô phỏng. Các khai báo cạnh tranh được rút gọn thành một giá trị cho mỗi thuộc tính theo nguồn gốc, mức độ quan trọng, lớp, độ cụ thể và thứ tự — đúng nghĩa cascade. Bố cục tuân theo mô hình hộp. Loại của một hộp và ngữ cảnh định dạng mà nó thiết lập quyết định cách đặt hộp đó và các phần tử anh em trong cùng dòng chảy. Mã nguồn của công cụ được tổ chức quanh đúng những mối quan tâm này (cascade, box/display, flex, float, bảng, phân mảnh). Vì vậy, bạn có thể lập luận về hành vi của nó dựa trên đặc tả, thay vì phải khám phá bằng thực nghiệm.

Bằng chứng cho thấy điều gì

Trang này là Evidence: Code-backed . Các giai đoạn và quy tắc ánh xạ tới kho lưu trữ core như sau:

Điểm vào trong tiến trình là writeHtml(string $html): static trong src/Core/Concerns/HasTextOutput.php.
Thiết kế một lượt, không giữ lại DOM, cùng các giới hạn về phần tử và lồng nhau chính là ADR-001 và mã tokenizer/parser/style-stack trong src/Html/.
Hợp đồng công cụ phân lớp — CSS parsing/applicators, trạng thái kiểu, bố cục, vẽ, phương tiện phân trang — chính là ADR-010, được phản ánh trong bố cục src/Html/ (ví dụ Cascade/, Css/, Flex/, Float/, Fragmentation/, và các lớp applicator).
Điểm nối ủy thác cho trình duyệt là writeHtmlChrome() trong cùng tệp, được tài liệu hóa là cần phần mở rộng kết xuất tùy chọn cùng với một tệp nhị phân Chrome/Chromium.

Các tiêu chuẩn giúp neo giữ tuyên bố về phạm vi một cách trung thực. Cascade rút gọn các khai báo cạnh tranh thành một giá trị duy nhất cho mỗi thuộc tính — nguồn gốc, mức độ quan trọng, lớp, độ cụ thể, thứ tự — theo Spec: CSS Cascade 5, §6.1 , và việc đặt vị trí trong dòng chảy tuân theo các quy tắc về hộp và ngữ cảnh định dạng theo Spec: CSS Display 3, §2 . Quan trọng không kém là ranh giới: một truy vấn tính năng tồn tại chính vì không phải mọi bộ xử lý đều hỗ trợ mọi tính năng theo Spec: CSS Conditional 5, §2 . Công cụ CSS của NextPDF là một tập con xác định, bám sát đặc tả; nói thẳng điều đó là một phần của hợp đồng.

Ví dụ thực tế

Kết xuất trong tiến trình chỉ là một lệnh gọi. Đầu ra là văn bản PDF có thể chọn được, không phải một trang đã raster hóa:

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Basic');
$doc->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">HTML Rendering in NextPDF</h1>
<p>NextPDF renders <strong>HTML and CSS</strong> directly into PDF pages,
<em>in-process</em>.</p>
<ul>
  <li>Headings, paragraphs, bold and italic</li>
  <li>Lists, tables, inline styles</li>
</ul>
HTML;

$doc->writeHtml($html);
$doc->save(__DIR__ . '/html-basic.pdf');

Nếu cùng tài liệu đó cần CSS hiện đại tùy ý với độ trung thực đúng như trình duyệt, lệnh gọi sẽ là writeHtmlChrome($html) — cùng tài liệu, đường kết xuất khác, và một phụ thuộc có chủ đích vào trình kết xuất trình duyệt tùy chọn.

Hiểu lầm thường gặp

Một hiểu lầm lặp lại nhiều lần là công cụ HTML thành PDF “về cơ bản là một trình duyệt.” Không phải vậy, và nó cũng không tự nhận như thế. Trình duyệt là một bản triển khai đồ sộ, được cập nhật liên tục, của toàn bộ nền tảng web. Công cụ trong tiến trình của NextPDF là một tập con bám sát đặc tả, tập trung vào bố cục tài liệu. Mô hình tư duy trung thực là “một công cụ CSS đủ năng lực cho tài liệu in,” không phải “Chrome trong PHP.” Khi bạn thực sự cần toàn bộ nền tảng, đó chính là mục đích của writeHtmlChrome(). Đây là một đường riêng biệt, phải chủ động chọn, có dấu chân vận hành riêng, không phải một phương án dự phòng âm thầm.

Một hiểu lầm thứ hai là cho rằng đường trình duyệt chỉ đơn thuần “kết xuất trang qua mạng.” Xét theo thiết kế, điều ngược lại mới đúng. Điểm nối ủy thác luôn kết xuất khi truy cập mạng cho tài nguyên con bị chặn — không có hình ảnh, phông chữ, biểu định kiểu hay khung từ xa — nên nó không thể trở thành một vector gửi yêu cầu ra ngoài. Độ trung thực từng điểm ảnh thì có; lối ra mạng mở thì không.

Giới hạn và ranh giới

Trang này giải thích hình dạng của quy trình và lựa chọn giữa trong tiến trình / trình duyệt. Nó không phải là ma trận hỗ trợ CSS. Chính xác những thuộc tính, mô-đun và bộ chọn nào mà công cụ trong tiến trình bao quát được xác định bởi mã nguồn và các bài kiểm thử tuân thủ của nó, không phải bởi tài liệu tổng quan này. Phạm vi đó thay đổi theo thời gian. Đường ủy thác cho trình duyệt cần một phần mở rộng tùy chọn và một tệp nhị phân Chrome/Chromium. Việc thiết lập, đặc tính vận hành và bố cục nội bộ của phần mở rộng đó nằm ngoài phạm vi ở đây và được tài liệu hóa cùng với gói đó. “Trong tiến trình” mô tả đường writeHtml() mặc định. Đây không phải là tuyên bố rằng mọi đường kết xuất đều tránh dùng tiến trình con. Các tuyên bố về kiến trúc là chính xác tính đến ngày rà soát của trang này. Các nguồn có thẩm quyền là src/Html/, ADR-001 và ADR-010 trong kho lưu trữ core.

Công cụ CSS trong tiến trình là một khả năng của Core. Điểm nối ủy thác cho trình duyệt là một phần mở rộng tùy chọn, và ở đây chỉ được nêu ở mức khả năng:

HTML rendering paths — edition availability
Edition	Availability
Core	Core cung cấp công cụ HTML/CSS trong tiến trình (writeHtml).
Pro	Đường ủy thác cho trình duyệt là một phần mở rộng bổ sung tùy chọn, độc lập với bậc phiên bản.
Enterprise	Đường ủy thác cho trình duyệt là một phần mở rộng bổ sung tùy chọn, độc lập với bậc phiên bản.

Tài liệu liên quan

Mô hình quy trình — vị trí của đường nội dung HTML trong dòng chảy tổng thể của tài liệu.
Khi nào không nên dùng NextPDF — các ranh giới trung thực, bao gồm cả trường hợp đường trình duyệt hoặc một công cụ khác phù hợp hơn.
Hướng dẫn quyết định tích hợp — lựa chọn giữa công cụ trong tiến trình và một trình kết xuất cho trường hợp của bạn.

Thuật ngữ

Kết xuất trong tiến trình — chuyển HTML/CSS thành PDF ngay trong tiến trình PHP, mặc định không cần trình duyệt hay tiến trình con (writeHtml()).
Một lượt / theo luồng — xử lý một luồng token từ trái sang phải mà không giữ lại cây DOM đầy đủ (ADR-001).
Cascade — quy trình CSS giải quyết các khai báo cạnh tranh thành một giá trị cho mỗi thuộc tính theo nguồn gốc, mức độ quan trọng, lớp, độ cụ thể và thứ tự.
Ngữ cảnh định dạng — môi trường bố cục mà một hộp thiết lập, chi phối cách đặt các nội dung trong dòng chảy của nó.
Hợp đồng lớp công cụ — bộ quy tắc được thực thi (ADR-010) xác định những gì mỗi lớp phân tích, kiểu, bố cục, vẽ và phương tiện phân trang được phép làm.
Điểm nối ủy thác cho trình duyệt — đường writeHtmlChrome() tùy chọn, kết xuất qua một trình duyệt headless với truy cập mạng cho tài nguyên con bị chặn.