HTML mit CSS gestalten

Auf einen Blick

Dieses Recipe zeigt, wie Sie CSS über Inline-style-Attribute und einen <style>-Block auf HTML-Inhalt anwenden. Außerdem erfahren Sie, wie Sie bestätigen, dass eine Eigenschaft verifiziert ist, bevor Sie sich auf sie verlassen.

Installation

composer require nextpdf/core:^3

Diese Einschränkung entspricht dem Paket nextpdf/core. Das Beispiel läuft mit PHP 8.4.

Konzeptioneller Überblick

Die HTML-Engine löst Styles über die CSS-Kaskade auf. Die Kaskade ist der Regelsatz, der entscheidet, welcher Style gewinnt, wenn mehrere Regeln dasselbe Element ansprechen. Die Engine liest zuerst den <style>-Block in der Eingabe und danach die Inline-style-Attribute. Sie gleicht beide mit Elementen ab und berechnet das Ergebnis in Kaskadenreihenfolge. Die Support-Matrix stuft das Modul CSS Cascading and Inheritance als „Verifiziert“ ein. Das bedeutet, dass eine eigene Fixture-Suite das Kaskaden- und Vererbungsverhalten absichert.

Eigenschaften zur Textdarstellung wie text-align, text-indent und letter-spacing stammen aus der Eigenschaftstabelle des CSS-Text-Moduls (W3C CSS Text Level 3). Die Schriftauswahl folgt dem CSS-Fonts-Modell. Die Kurzschreibweise font setzt font-style, font-variant, font-weight, font-size und font-family gemeinsam (W3C CSS Fonts Level 3).

Die Unterstützung richtet sich nach den jeweiligen W3C-Modulen und ist wahrheitsgeprüft. Eine Eigenschaft, die implementiert ist, aber keine eigene Modul-Fixture hat, wird als „Beansprucht“ eingestuft, nicht als „Verifiziert“. Behandeln Sie „Beansprucht“ als Best Effort und validieren Sie das visuelle Ergebnis für Ihre Inhalte. Behandeln Sie „Verifiziert“ als durch eine bestandene Fixture-Suite abgesichert.

API-Oberfläche

Sie steuern die gesamte Gestaltung über das HTML, das Sie an writeHtml(string $html): static übergeben (NextPDF\Core\Concerns\HasTextOutput). Es gibt keine separate CSS-API, und die Kaskade läuft intern ab. Die vollständige PHPDoc-Tabelle wird aus dem Quellcode generiert.

Codebeispiel — Schnellstart

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

Codebeispiel — Produktion

Dieses Beispiel ist eigenständig und im Harness lauffähig. Es deckt einen <style>-Block, Klassenselektoren, Inline-Styles sowie den Familien- und Gewichtspfad von font ab.

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

Erwartete STDOUT:

Wrote style-with-css.pdf

Randfälle & Stolperfallen

Kaskadenreihenfolge. In der Kaskade gewinnt ein Inline-style gegenüber einem <style>-Block-Selektor mit gleicher Spezifität. Wenn Sie eine unerwartete Farbe sehen, prüfen Sie zuerst, ob ein Inline-Override vorliegt.
Beansprucht vs. Verifiziert. text-align, text-indent und color sind in der Matrix als „Beansprucht“ eingestuft. Sie sind implementiert, haben aber keine eigene Modul-Fixture. Sie werden gerendert; validieren Sie für die Produktionsfreigabe dennoch die visuelle Ausgabe.
Kein gespeicherter Baum. Die Streaming-Engine (ADR-001) hält keinen Dokumentbaum, daher kann sie keinen Selektor anwenden, bei dem ein späteres Geschwisterelement ein früheres Element umgestaltet. Reihenfolgeunabhängige Selektoren sind eingeschränkt.
Nicht unterstützte Eigenschaft. Eine nicht unterstützte Eigenschaft wird ignoriert und nicht als Fehler gemeldet. Prüfen Sie sie anhand der Matrix, bevor Sie sich darauf verlassen.
Farbräume. Lab-, LCH- und OKLab-Werte werden geparst, aber die PDF-Farbraumtreue für diese Funktionen ist nicht zugesichert (Matrix: „Beansprucht“ für CSS Color 4).

Performance

Die Kaskadenauflösung erfolgt in einem einzelnen Durchlauf. Der Aufwand bleibt linear zur Tokenanzahl, O(n). Das Budget ist wall_ms: 1500, peak_mb: 96. Ein <style>-Block verursacht einen einmaligen Selektor-Parse-Aufwand, der proportional zur Anzahl der Regeln ist.

Auszug aus der CSS-Support-Matrix (nur verifizierte Zeilen)

Dieser Auszug enthält nur die verifizierten Zeilen aus der wahrheitsgeprüften CSS-Support-Matrix.

W3C-Modul	Level	Status	Nachweis
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verifiziert	`src/Html/Cascade/`, `tests/Unit/Html/Cascade/`
CSS Cascading (`css_cascade_4`)	4	Verifiziert	`Cascade/Layer/` + revert/layer-Tests
CSS Cascading (`css_cascade_5`)	5	Verifiziert	`AtRule/Layer/`- + `Cascade/Layer/`-Suites
CSS Fonts (`css_fonts_3`)	3	Verifiziert	`src/Html/Font/`, `tests/Unit/Font/` + FontResolver-Tests
CSS Fonts (`css_fonts_4`)	4	Verifiziert	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color und background-color sind in der Matrix „Beansprucht“. Die Tabelle führt sie deshalb bewusst nicht unter den verifizierten Zeilen auf.

Einschränkungen des Single-Pass-Streamings (ADR-001)

Die Kaskade verarbeitet eine gestreamte Token-Liste ohne DOM; Selektoren werden daher anhand des Kontexts in Dokumentreihenfolge aufgelöst. Selektorfälle, die den gesamten Baum benötigen, sind gemäß ADR-006 eingeschränkt. Schreiben Sie CSS, das nur von der Dokumentreihenfolge und dem Kontext der Vorfahren abhängt.

Layer-Verträge (ADR-010)

Das CSS-Parsing gehört zur Kaskadenschicht, und der Layout-Dispatch darf rohe $css[...]-Werte nicht direkt lesen. Die öffentliche Oberfläche ist die HTML-Eingabe. Es gibt keinen unterstützten Weg, berechnete Styles an der Kaskade vorbei einzuschleusen.

Speicherbudget für große Dokumente

Die Kaskade hält den aktiven Regelsatz und den Push-and-Pop-Style-Stack vor, nicht einen Knotenbaum. Containerbezogene Kontexte halten sich an das ADR-020-Budget (5,000 Knoten pro Kontext, 50 MB aktive Obergrenze). Große Stylesheets erhöhen den Speicherbedarf des Regelsatzes linear; halten Sie die Selektoranzahl daher begrenzt.

Sicherheitshinweise

CSS in nicht vertrauenswürdigem HTML kann keinen Code ausführen, aber das Layout und Ressourcenverweise beeinflussen (zum Beispiel background-image). Die Standardrichtlinie für externe Ressourcen ruft keine beliebigen Remote-URLs ab. Bereinigen Sie jedes HTML und CSS, das Sie aus Benutzereingaben zusammensetzen, bevor Sie es rendern.

Konformität

Aussage	Spezifikation	Abschnitt	reference_id
Text-Eigenschaften (text-align, text-indent, letter-spacing) werden durch die CSS-Text-Eigenschaftstabelle definiert.	W3C CSS Text Level 3	css_text_3#x1.x24
Die font-Kurzschreibweise setzt font-style, font-variant, font-weight, font-size und font-family.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Dieses Recipe zeigt, wie NextPDF eine unterstützte CSS-Teilmenge anwendet; es behauptet keine vollständige CSS-Unterstützung. Den verifizierten Status pro Modul findest du in der CSS-Support-Matrix.

Kommerzieller Kontext

Nicht zutreffend.