Stylizowanie HTML za pomocą CSS

W skrócie

Ten przepis pokazuje, jak stosować arkusze stylów kaskadowych (CSS) do treści w języku Hypertext Markup Language (HTML). Wykorzystuje atrybuty style inline oraz blok <style>. Pokazuje też, jak potwierdzić, że właściwość jest zweryfikowana, zanim zaczniesz na niej polegać.

Instalacja

composer require nextpdf/core:^3

Użyj tego ograniczenia wersji dla pakietu nextpdf/core. Przykład działa na PHP 8.4.

Przegląd koncepcyjny

Silnik HTML rozstrzyga style za pomocą kaskady CSS. Kaskada decyduje, który styl ma pierwszeństwo, gdy kilka reguł dotyczy tego samego elementu. Silnik odczytuje najpierw wejściowy blok <style>, a następnie atrybuty style inline. Dopasowuje oba do elementów i oblicza wynik zgodnie z kolejnością kaskady. Macierz wsparcia ocenia moduł CSS Cascading and Inheritance jako Verified, co oznacza, że dedykowany zestaw fikstur obejmuje zachowanie kaskady i dziedziczenia.

Właściwości prezentacji tekstu, takie jak text-align, text-indent i letter-spacing, są zdefiniowane w tabeli właściwości modułu CSS Text konsorcjum World Wide Web Consortium (W3C) (W3C CSS Text Level 3). Dobór czcionki korzysta z modelu CSS Fonts. Skrót font ustawia łącznie font-style, font-variant, font-weight, font-size i font-family (W3C CSS Fonts Level 3).

Obsługa jest śledzona według modułów W3C i audytowana pod kątem zgodności z faktami. Właściwość może być zaimplementowana, a mimo to nie mieć dedykowanej fikstury modułu; w takim przypadku ma status „Claimed”, a nie „Verified”. Traktuj „Claimed” jako deklarację najlepszych starań i zweryfikuj wynik wizualny dla swojej treści. Traktuj „Verified” jako status poparty zestawem fikstur, który przechodzi testy.

Powierzchnia API

Stylami sterujesz przez HTML przekazywany do writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Nie ma osobnego interfejsu programowania aplikacji (API) dla CSS; kaskada działa wewnętrznie. Pełna tabela PHPDoc jest generowana z kodu źródłowego.

Przykład kodu — szybki start

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

Przykład kodu — produkcja

Ten samodzielny przykład nadaje się do uruchomienia w środowisku testowym (harness). Wykorzystuje blok <style>, selektory klas, style inline oraz ścieżkę font dla rodziny i grubości czcionki.

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

Oczekiwane standardowe wyjście (STDOUT):

Wrote style-with-css.pdf

Przypadki brzegowe i pułapki

Kolejność kaskady. W kaskadzie styl inline style ma pierwszeństwo przed selektorem z bloku <style> o równej specyficzności. Jeśli widzisz nieoczekiwany kolor, najpierw sprawdź, czy nie występuje nadpisanie inline.
Claimed kontra Verified. text-align, text-indent i color mają w macierzy status „Claimed”. Są zaimplementowane, ale nie mają dedykowanej fikstury modułu. Są renderowane, ale przed zatwierdzeniem do produkcji należy zweryfikować wynik wizualny.
Brak zachowanego drzewa. Silnik strumieniowy, opisany w Architecture Decision Record (ADR-001), nie zachowuje drzewa dokumentu, więc nie może zastosować selektora, w którym późniejszy element rodzeństwa zmienia styl wcześniejszego elementu. W rezultacie ograniczone są selektory niezależne od kolejności.
Nieobsługiwana właściwość. Nieobsługiwana właściwość jest ignorowana, a nie zgłaszana jako błąd. Sprawdź macierz, zanim zaczniesz na niej polegać.
Przestrzenie kolorów. Wartości Lab, LCH i OKLab są parsowane, ale wierność odwzorowania przestrzeni kolorów w formacie Portable Document Format (PDF) dla tych funkcji nie jest gwarantowana (macierz: „Claimed” dla CSS Color 4).

Wydajność

Rozstrzyganie kaskady odbywa się w jednym przebiegu. Koszt pozostaje liniowy względem liczby tokenów, O(n). Budżet wynosi wall_ms: 1500, peak_mb: 96. Blok <style> dodaje jednorazowy koszt parsowania selektorów, proporcjonalny do liczby reguł.

Fragment macierzy wsparcia CSS (tylko wiersze Verified)

Ten fragment pokazuje wyłącznie wiersze Verified z macierzy wsparcia CSS audytowanej pod kątem zgodności z faktami.

Moduł W3C	Poziom	Status	Dowody
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/` + testy revert/layer
CSS Cascading (`css_cascade_5`)	5	Verified	`AtRule/Layer/` + zestawy `Cascade/Layer/`
CSS Fonts (`css_fonts_3`)	3	Verified	`src/Html/Font/`, `tests/Unit/Font/` + testy FontResolver
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color i background-color mają w macierzy status „Claimed”. Tabela celowo pomija je w wierszach Verified.

Ograniczenia strumieniowania jednoprzebiegowego (ADR-001)

Kaskada działa na strumieniowej liście tokenów bez modelu Document Object Model (DOM), więc selektory są rozstrzygane względem kontekstu kolejności dokumentu. Przypadki selektorów obejmujące całe drzewo są ograniczone zgodnie z ADR-006. Pisz CSS, który zależy wyłącznie od kolejności dokumentu i kontekstu przodków.

Kontrakty warstw (ADR-010)

Parsowanie CSS należy do warstwy kaskady, a dyspozytor układu nie może bezpośrednio odczytywać surowych wartości $css[...]. Publiczną powierzchnią jest wejście HTML. Nie istnieje obsługiwany sposób wstrzykiwania obliczonych stylów z pominięciem kaskady.

Budżet pamięci dla dużych dokumentów

Kaskada przechowuje aktywny zestaw reguł oraz stos stylów typu push i pop, a nie drzewo węzłów. Konteksty o zasięgu kontenera respektują budżet ADR-020 (5,000 węzłów na kontekst, aktywny limit 50 MB). Duże arkusze stylów liniowo zwiększają pamięć zestawu reguł, więc ograniczaj liczbę selektorów.

Uwagi dotyczące bezpieczeństwa

CSS osadzony w niezaufanym HTML nie może uruchamiać kodu, ale może wpływać na układ i odwołania do zasobów, takie jak background-image. Domyślna polityka zasobów zewnętrznych nie pobiera dowolnych zdalnych adresów URL. Oczyść każdy HTML i CSS składany z danych wejściowych użytkownika przed renderowaniem.

Zgodność

Stwierdzenie	Specyfikacja	Klauzula	reference_id
Właściwości tekstu (text-align, text-indent, letter-spacing) są zdefiniowane przez tabelę właściwości CSS Text.	W3C CSS Text Level 3	css_text_3#x1.x24
Skrót font ustawia font-style, font-variant, font-weight, font-size i font-family.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Ten przepis pokazuje, jak NextPDF stosuje obsługiwany podzbiór CSS; nie gwarantuje pełnej obsługi CSS. Aby poznać zweryfikowany status poszczególnych modułów, zobacz macierz wsparcia CSS.

Kontekst komercyjny

Nie dotyczy.