HTML opmaken met CSS

In een oogopslag

In dit recipe pas je Cascading Style Sheets (CSS) toe op Hypertext Markup Language (HTML)-inhoud. Het gebruikt inline-style-attributen en een <style>-blok. Je leert ook hoe je controleert of een eigenschap geverifieerd is voordat je erop vertrouwt.

Installeren

composer require nextpdf/core:^3

Gebruik deze constraint voor het pakket nextpdf/core. Het voorbeeld draait op PHP 8.4.

Conceptueel overzicht

De HTML-engine bepaalt stijlen via de CSS-cascade. De cascade bepaalt welke stijl wint wanneer meerdere regels op hetzelfde element gericht zijn. De engine leest eerst het invoer-<style>-blok en daarna de inline-style-attributen. Beide worden tegen elementen gematcht en het resultaat wordt in cascadevolgorde berekend. De ondersteuningsmatrix beoordeelt de CSS Cascading and Inheritance-module als Verified. Dat betekent dat een gerichte fixture-suite het gedrag van cascade en overerving dekt.

Tekstpresentatie-eigenschappen zoals text-align, text-indent en letter-spacing zijn gedefinieerd in de eigenschappentabel van de CSS Text-module van het World Wide Web Consortium (W3C) (W3C CSS Text Level 3). Lettertypeselectie gebruikt het CSS Fonts-model. De verkorte notatie font stelt font-style, font-variant, font-weight, font-size en font-family in één keer in (W3C CSS Fonts Level 3).

Ondersteuning wordt per W3C-module bijgehouden en op correctheid gecontroleerd. Een eigenschap kan geïmplementeerd zijn en toch geen gerichte module-fixture hebben; in dat geval wordt deze beoordeeld als “Claimed”, niet als “Verified”. Beschouw “Claimed” als een inspanningsverplichting en valideer het visuele resultaat voor je inhoud. Beschouw “Verified” als ondersteund door een slagende fixture-suite.

API-oppervlak

Je bepaalt de opmaak via de HTML die je doorgeeft aan writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Er is geen aparte application programming interface (API) voor CSS; de cascade draait intern. De volledige PHPDoc-tabel wordt vanuit de broncode gegenereerd.

Codevoorbeeld — Snelstart

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

Codevoorbeeld — Productie

Dit zelfstandige voorbeeld kan in het testharnas draaien. Het test een <style>-blok, klasseselectors, inline-stijlen en het pad voor font-familie en -gewicht.

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

Verwachte standaarduitvoer (STDOUT):

Wrote style-with-css.pdf

Randgevallen en valkuilen

Cascadevolgorde. In de cascade wint een inline style van een selector in een <style>-blok met gelijke specificiteit. Controleer eerst of er een inline-overschrijving is als je een onverwachte kleur ziet.
Claimed versus Verified. text-align, text-indent en color worden in de matrix beoordeeld als “Claimed”. Ze zijn geïmplementeerd, maar hebben geen gerichte module-fixture. Ze worden weergegeven, maar je moet de visuele uitvoer valideren voordat je deze voor productie goedkeurt.
Geen behouden boom. De streaming-engine, beschreven in Architecture Decision Record (ADR-001), houdt geen documentboom bij, dus kan geen selector toepassen waarbij een later broer-of-zus-element een eerder element opnieuw opmaakt. Daardoor zijn volgorde-onafhankelijke selectors beperkt.
Niet-ondersteunde eigenschap. Een niet-ondersteunde eigenschap wordt genegeerd, niet als fout gemeld. Raadpleeg de matrix voordat je erop vertrouwt.
Kleurruimten. Waarden in Lab, LCH en OKLab worden ontleed, maar de kleurruimtegetrouwheid in Portable Document Format (PDF) voor die functies wordt niet gegarandeerd (matrix: “Claimed” voor CSS Color 4).

Prestaties

Cascade-resolutie gebeurt in één enkele doorloop. De kosten blijven lineair in het aantal tokens, O(n). Het budget is wall_ms: 1500, peak_mb: 96. Een <style>-blok voegt een eenmalige kostenpost voor het ontleden van selectors toe, evenredig aan het aantal regels.

Fragment uit de CSS-ondersteuningsmatrix (alleen Verified-rijen)

Dit fragment toont alleen de Verified-rijen uit de op correctheid gecontroleerde CSS-ondersteuningsmatrix.

W3C-module	Niveau	Status	Bewijs
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/` + revert/layer-tests
CSS Cascading (`css_cascade_5`)	5	Verified	`AtRule/Layer/`- + `Cascade/Layer/`-suites
CSS Fonts (`css_fonts_3`)	3	Verified	`src/Html/Font/`, `tests/Unit/Font/` + FontResolver-tests
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color en background-color zijn “Claimed” in de matrix. De tabel laat ze bewust weg uit de Verified-rijen.

Beperkingen van single-pass streaming (ADR-001)

De cascade loopt over een gestreamde tokenlijst zonder Document Object Model (DOM), dus selectors worden bepaald aan de hand van de context in documentvolgorde. Selectorgevallen die de volledige boom vereisen, zijn beperkt volgens ADR-006. Schrijf CSS die alleen afhankelijk is van de documentvolgorde en de context van bovenliggende elementen.

Layercontracten (ADR-010)

Het ontleden van CSS hoort thuis in de cascade-laag, en de lay-outdispatch mag ruwe $css[...]-waarden niet rechtstreeks lezen. Het publieke oppervlak is de HTML-invoer. Er is geen ondersteunde manier om berekende stijlen buiten de cascade om te injecteren.

Geheugenbudget voor grote documenten

De cascade houdt de actieve regelset en de push-en-pop-stijlstack bij, geen knooppuntboom. Contexten met containerbereik houden zich aan het budget van ADR-020 (5,000 knooppunten per context, een actief plafond van 50 MB). Grote stylesheets laten het geheugen voor de regelset lineair groeien, dus houd het aantal selectors beperkt.

Beveiligingsopmerkingen

CSS in niet-vertrouwde HTML kan geen code uitvoeren, maar kan wel de lay-out en resourceverwijzingen beïnvloeden, zoals background-image. Het standaardbeleid voor externe resources haalt geen willekeurige externe URL’s op. Saneer alle HTML en CSS die je uit gebruikersinvoer samenstelt voordat je deze weergeeft.

Conformiteit

Bewering	Spec	Clausule	reference_id
Teksteigenschappen (text-align, text-indent, letter-spacing) worden gedefinieerd door de eigenschappentabel van CSS Text.	W3C CSS Text Level 3	css_text_3#x1.x24
De verkorte notatie font stelt font-style, font-variant, font-weight, font-size en font-family in.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Dit recipe laat zien hoe NextPDF een ondersteunde subset van CSS toepast; het beweert geen volledige CSS-ondersteuning. Raadpleeg de CSS-ondersteuningsmatrix voor de geverifieerde status per module.

Commerciële context

Niet van toepassing.