Applicare stili all'HTML con i CSS

In breve

Questa ricetta applica i CSS al contenuto HTML tramite attributi style inline e un blocco <style>. Mostra inoltre come verificare che una proprietà risulti confermata prima di farvi affidamento.

Installazione

composer require nextpdf/core:^3

Questo vincolo corrisponde al pacchetto nextpdf/core. L’esempio viene eseguito con PHP 8.4.

Panoramica concettuale

Il motore HTML risolve gli stili tramite la cascata CSS. La cascata è l’insieme di regole che decide quale stile prevale quando più regole puntano allo stesso elemento. Il motore legge prima il blocco <style> nell’input, poi gli attributi style inline. Confronta entrambi con gli elementi e calcola il risultato secondo l’ordine della cascata. La matrice di supporto classifica il modulo CSS Cascading and Inheritance come Verificato, il che significa che una suite di fixture dedicata garantisce il comportamento della cascata e dell’ereditarietà.

Le proprietà di presentazione del testo come text-align, text-indent e letter-spacing provengono dalla tabella delle proprietà del modulo CSS Text (W3C CSS Text Level 3). La selezione dei font utilizza il modello CSS Fonts. La proprietà abbreviata font imposta insieme font-style, font-variant, font-weight, font-size e font-family (W3C CSS Fonts Level 3).

Il supporto segue ogni modulo W3C ed è sottoposto a verifica di attendibilità. Una proprietà implementata ma priva di una fixture di modulo dedicata viene classificata come «Dichiarata», non «Verificata». Considerare «Dichiarata» come supporto fornito al meglio delle possibilità e convalidare il risultato visivo per il proprio contenuto. Considerare «Verificata» come garantita da una suite di fixture superata.

Superficie dell’API

L’applicazione degli stili è interamente controllata dall’HTML passato a writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Non esiste un’API CSS separata e la cascata viene eseguita internamente. La tabella PHPDoc completa è generata dal codice sorgente.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Questo esempio è autonomo ed eseguibile tramite l’harness di test. Mette alla prova un blocco <style>, i selettori di classe, gli stili inline e il percorso relativo a famiglia e peso del 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";

STDOUT previsto:

Wrote style-with-css.pdf

Casi limite e insidie

Ordine di cascata. Secondo la cascata, un attributo style inline prevale su un selettore definito nel blocco <style> a pari specificità. Se si riscontra un colore inatteso, verificare innanzitutto la presenza di un override inline.
«Dichiarata» rispetto a «Verificata». text-align, text-indent e color sono classificati come «Dichiarata» nella matrice. Sono implementati ma non dispongono di una fixture di modulo dedicata. Vengono renderizzati, ma è opportuno convalidare l’output visivo per l’approvazione in produzione.
Nessun albero mantenuto. Il motore di streaming (ADR-001) non mantiene alcun albero del documento, pertanto non può applicare un selettore per cui un elemento fratello successivo modifica lo stile di un elemento precedente. I selettori indipendenti dall’ordine sono soggetti a vincoli.
Proprietà non supportata. Una proprietà non supportata viene ignorata; non produce un errore. Verificare nella matrice prima di farvi affidamento.
Spazi colore. I valori Lab, LCH e OKLab vengono analizzati, ma la fedeltà dello spazio colore nel PDF per tali funzioni non è garantita (matrice: «Dichiarata» per CSS Color 4).

Prestazioni

La risoluzione della cascata fa parte del passaggio unico. Il costo rimane lineare rispetto al numero di token, O(n). Il budget è wall_ms: 1500, peak_mb: 96. Un blocco <style> aggiunge un costo una tantum per l’analisi dei selettori, proporzionale al numero di regole.

Estratto della matrice di supporto CSS (solo righe Verificate)

Questo estratto riproduce solo le righe Verificate della matrice di supporto CSS sottoposta a verifica di attendibilità.

Modulo W3C	Livello	Stato	Evidenza
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verificata	`src/Html/Cascade/`, `tests/Unit/Html/Cascade/`
CSS Cascading (`css_cascade_4`)	4	Verificata	`Cascade/Layer/` + test revert/layer
CSS Cascading (`css_cascade_5`)	5	Verificata	`AtRule/Layer/` + `Cascade/Layer/` (suite)
CSS Fonts (`css_fonts_3`)	3	Verificata	`src/Html/Font/`, `tests/Unit/Font/` + test FontResolver
CSS Fonts (`css_fonts_4`)	4	Verificata	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color e background-color hanno stato «Dichiarata» nella matrice. La tabella le esclude deliberatamente dalle righe Verificate.

Vincoli dello streaming a passaggio unico (ADR-001)

La cascata opera su un elenco di token in streaming senza DOM; pertanto i selettori si risolvono rispetto al contesto secondo l’ordine del documento. I selettori che richiedono l’intero albero sono soggetti a vincoli secondo ADR-006. Scrivere CSS che dipendano solo dall’ordine del documento e dal contesto degli elementi antenati.

Contratti dei livelli (ADR-010)

L’analisi dei CSS appartiene al livello di cascata e il dispatch dell’impaginazione non deve leggere direttamente i valori grezzi $css[...]. La superficie pubblica è l’input HTML. Non esiste una modalità supportata per iniettare stili calcolati oltre la cascata.

Budget di memoria per documenti di grandi dimensioni

La cascata mantiene il set di regole attivo e lo stack degli stili per le operazioni push e pop, non un albero di nodi. I contesti con ambito di container rispettano il budget ADR-020 (5,000 nodi per contesto, limite massimo attivo di 50 MB). I fogli di stile di grandi dimensioni aumentano linearmente la memoria del set di regole, quindi è opportuno mantenere limitato il numero di selettori.

Note sulla sicurezza

Il CSS presente in codice HTML non attendibile non può eseguire codice, ma può influire sull’impaginazione e sui riferimenti alle risorse (per esempio background-image). I criteri predefiniti per le risorse esterne non recuperano URL remoti arbitrari. Sanificare qualsiasi codice HTML e CSS assemblato dall’input dell’utente prima di renderizzarlo.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
Le proprietà del testo (text-align, text-indent, letter-spacing) sono definite dalla tabella delle proprietà CSS Text.	W3C CSS Text Level 3	css_text_3#x1.x24
La proprietà abbreviata font imposta font-style, font-variant, font-weight, font-size e font-family.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Questa ricetta mostra come NextPDF applica un sottoinsieme supportato di CSS; non garantisce il supporto completo di CSS. Per lo stato di verifica di ciascun modulo, consultare la matrice di supporto CSS.

Contesto commerciale

Non applicabile.