Tạo kiểu HTML bằng CSS

Tổng quan nhanh

Hướng dẫn này trình bày cách áp dụng Cascading Style Sheets (CSS) cho nội dung Hypertext Markup Language (HTML). Hướng dẫn dùng thuộc tính style nội tuyến và một khối <style>. Bạn cũng sẽ biết cách xác nhận một thuộc tính đã được xác minh trước khi dựa vào thuộc tính đó.

Cài đặt

composer require nextpdf/core:^3

Dùng ràng buộc này cho gói nextpdf/core. Ví dụ chạy trên PHP 8.4.

Tổng quan khái niệm

Bộ máy HTML phân giải kiểu thông qua cascade của CSS. Cascade quyết định kiểu nào thắng khi nhiều quy tắc cùng nhắm đến một phần tử. Bộ máy đọc khối <style> đầu vào trước, rồi đến các thuộc tính style nội tuyến. Bộ máy khớp cả hai với các phần tử và tính kết quả theo thứ tự cascade. Bảng hỗ trợ xếp module CSS Cascading and Inheritance ở mức Verified, nghĩa là có một bộ fixture chuyên dụng bao phủ hành vi cascade và kế thừa.

Các thuộc tính trình bày văn bản như text-align, text-indent và letter-spacing được định nghĩa trong bảng thuộc tính của module CSS Text do World Wide Web Consortium (W3C) công bố (W3C CSS Text Level 3). Việc chọn phông chữ dùng mô hình CSS Fonts. Cú pháp rút gọn font thiết lập đồng thời font-style, font-variant, font-weight, font-size và font-family (W3C CSS Fonts Level 3).

Mức hỗ trợ được theo dõi theo từng module W3C và được xác minh. Một thuộc tính có thể đã được hiện thực nhưng vẫn thiếu fixture module chuyên dụng; trong trường hợp đó, thuộc tính này được xếp ở mức “Claimed”, không phải “Verified”. Hãy xem “Claimed” là mức nỗ lực tối đa và kiểm tra kết quả hiển thị cho nội dung của bạn. Hãy xem “Verified” là mức được bảo chứng bằng một bộ fixture đạt yêu cầu.

Bề mặt API

Bạn kiểm soát kiểu dáng thông qua HTML truyền vào writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Không có giao diện lập trình ứng dụng (API) riêng cho CSS; cascade chạy bên trong. Bảng PHPDoc đầy đủ được tạo từ mã nguồn.

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

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->writeHtml(
    '<style>.lead { color: #1E3A8A; text-align: center; }</style>'
    . '<p class="lead">Styled with a style block.</p>'
);

$doc->save(__DIR__ . '/out.pdf');

Mẫu mã — sản xuất

Ví dụ độc lập này có thể chạy trong harness. Ví dụ kiểm thử một khối <style>, bộ chọn theo class, kiểu nội tuyến, cùng đường xử lý họ phông chữ và độ đậm của font.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('CSS Styling');
$doc->addPage();

$html = <<<'HTML'
<style>
    h1        { color: #1E3A8A; }
    .lead     { color: #D97706; font-size: 14px; }
    .callout  { background-color: #EFF6FF; padding: 8px; border: 1px solid #BFDBFE; }
    .centered { text-align: center; }
</style>

<h1>Styling HTML with CSS</h1>

<p class="lead">This paragraph is styled through a class selector in a
style block.</p>

<p class="callout">This paragraph has a background, padding, and a border
from a class selector.</p>

<p class="centered" style="font-weight: bold;">Centered, with an inline
override for weight.</p>

<p style="color: #6B7280; font-size: 9px;">Inline style only.</p>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/style-with-css.pdf');

echo "Wrote style-with-css.pdf\n";

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

Wrote style-with-css.pdf

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

Thứ tự cascade. Trong cascade, một style nội tuyến thắng một bộ chọn trong khối <style> khi có cùng độ ưu tiên. Nếu thấy một màu không như dự kiến, trước tiên hãy kiểm tra xem có kiểu nội tuyến nào ghi đè hay không.
Claimed so với Verified. text-align, text-indent và color được xếp ở mức “Claimed” trong bảng. Chúng đã được hiện thực, nhưng không có fixture module chuyên dụng. Chúng vẫn kết xuất, nhưng bạn nên kiểm tra kết quả hiển thị trước khi phê duyệt cho sản xuất.
Không lưu giữ cây. Bộ máy streaming, được mô tả trong Architecture Decision Record (ADR-001), không lưu giữ cây tài liệu, nên không thể áp dụng một bộ chọn trong đó một phần tử anh em đứng sau tạo lại kiểu cho một phần tử đứng trước. Do đó, các bộ chọn không phụ thuộc thứ tự bị hạn chế.
Thuộc tính không được hỗ trợ. Một thuộc tính không được hỗ trợ sẽ bị bỏ qua, không phát sinh lỗi. Hãy kiểm tra bảng trước khi bạn dựa vào nó.
Không gian màu. Các giá trị Lab, LCH và OKLab được phân tích, nhưng độ trung thực không gian màu trong Portable Document Format (PDF) cho các hàm đó không được khẳng định (bảng: “Claimed” cho CSS Color 4).

Hiệu năng

Việc phân giải cascade diễn ra trong một lượt duy nhất. Chi phí duy trì tuyến tính theo số lượng token, O(n). Ngân sách là wall_ms: 1500, peak_mb: 96. Một khối <style> thêm chi phí phân tích bộ chọn tỉ lệ với số lượng quy tắc.

Trích bảng hỗ trợ CSS (chỉ các hàng Verified)

Trích đoạn này chỉ hiển thị các hàng Verified từ bảng hỗ trợ CSS đã được xác minh.

Module W3C	Cấp	Trạng thái	Bằng chứng
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`, `tests/Unit/Html/Cascade/`
CSS Cascading (`css_cascade_4`)	4	Verified	`Cascade/Layer/` + các test revert/layer
CSS Cascading (`css_cascade_5`)	5	Verified	`AtRule/Layer/` + `Cascade/Layer/` các bộ test
CSS Fonts (`css_fonts_3`)	3	Verified	`src/Html/Font/`, `tests/Unit/Font/` + các test FontResolver
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color và background-color ở mức “Claimed” trong bảng. Bảng cố ý không đưa các thuộc tính này vào các hàng Verified.

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

Cascade chạy trên một danh sách token được truyền theo luồng mà không có Document Object Model (DOM), nên các bộ chọn được phân giải theo ngữ cảnh thứ tự tài liệu. Các trường hợp bộ chọn trên toàn cây bị hạn chế theo ADR-006. Hãy viết CSS chỉ phụ thuộc vào thứ tự tài liệu và ngữ cảnh tổ tiên.

Hợp đồng của layer (ADR-010)

Việc phân tích CSS thuộc về layer cascade, và bộ điều phối bố cục không được đọc trực tiếp các giá trị $css[...] thô. Bề mặt công khai là đầu vào HTML. Không có cách nào được hỗ trợ để chèn các kiểu đã tính toán vượt qua cascade.

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

Cascade giữ bộ quy tắc đang hoạt động và ngăn xếp kiểu push và pop, chứ không giữ một cây nút. Các ngữ cảnh giới hạn theo container tuân theo ngân sách ADR-020 (5,000 nút mỗi ngữ cảnh, trần hoạt động 50 MB). Các stylesheet lớn làm tăng bộ nhớ của bộ quy tắc theo tuyến tính, nên hãy giữ số lượng bộ chọn trong giới hạn.

Lưu ý bảo mật

CSS trong HTML không tin cậy không thể chạy mã, nhưng có thể ảnh hưởng đến bố cục và các tham chiếu tài nguyên, chẳng hạn như background-image. Chính sách tài nguyên bên ngoài mặc định không tải các URL từ xa tùy ý. Hãy làm sạch mọi HTML và CSS được dựng từ dữ liệu người dùng nhập trước khi kết xuất.

Tuân thủ

Tuyên bố	Đặc tả	Điều khoản	reference_id
Các thuộc tính văn bản (text-align, text-indent, letter-spacing) được định nghĩa bởi bảng thuộc tính CSS Text.	W3C CSS Text Level 3	css_text_3#x1.x24
Cú pháp rút gọn font thiết lập font-style, font-variant, font-weight, font-size và font-family.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Hướng dẫn này cho thấy cách NextPDF áp dụng một tập con CSS được hỗ trợ; hướng dẫn không khẳng định hỗ trợ CSS đầy đủ. Để biết trạng thái đã xác minh theo từng module, hãy xem bảng hỗ trợ CSS.

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

Không áp dụng.