Aplicar CSS al HTML

Vistazo rápido

Esta receta aplica CSS al contenido HTML mediante atributos style en línea y un bloque <style>. También muestra cómo confirmar que una propiedad está verificada antes de depender de ella.

Instalación

composer require nextpdf/core:^3

Esta restricción coincide con el paquete nextpdf/core. El ejemplo se ejecuta con PHP 8.4.

Descripción conceptual

El motor HTML resuelve los estilos mediante la cascada de CSS. La cascada es el conjunto de reglas que decide qué estilo prevalece cuando varias reglas afectan al mismo elemento. El motor lee primero el bloque <style> de la entrada y, después, los atributos style en línea. Compara ambos con los elementos y calcula el resultado según el orden de la cascada. La matriz de compatibilidad califica el módulo CSS Cascading and Inheritance como Verified, lo que significa que una suite específica de fixtures respalda el comportamiento de la cascada y la herencia.

Las propiedades de presentación de texto, como text-align, text-indent y letter-spacing, proceden de la tabla de propiedades del módulo CSS Text (W3C CSS Text Level 3). La selección de fuentes usa el modelo CSS Fonts. La abreviatura font establece font-style, font-variant, font-weight, font-size y font-family a la vez (W3C CSS Fonts Level 3).

La compatibilidad sigue cada módulo del W3C y se audita con rigor. Una propiedad implementada que no tiene un fixture de módulo específico se califica como «Claimed», no como «Verified». «Claimed» debe entenderse como el mejor esfuerzo posible; valide el resultado visual para su contenido. «Verified» debe entenderse como respaldado por una suite de fixtures que se supera correctamente.

Superficie de la API

Todo el estilo se controla mediante el HTML que se pasa a writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). No hay una API de CSS independiente y la cascada se ejecuta de forma interna. La tabla completa de PHPDoc se genera a partir del código fuente.

Ejemplo de código: inicio rápido

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

Ejemplo de código: producción

Este ejemplo es autónomo y se puede ejecutar en el arnés de pruebas. Ejercita un bloque <style>, selectores de clase, estilos en línea y la ruta de familia y grosor de 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 esperado:

Wrote style-with-css.pdf

Casos límite y problemas comunes

Orden de la cascada. Según la cascada, un style en línea prevalece sobre un selector de bloque <style> con la misma especificidad. Si aparece un color inesperado, conviene comprobar primero si hay una anulación en línea.
Claimed frente a Verified. text-align, text-indent y color se califican como «Claimed» en la matriz. Están implementadas, pero no tienen un fixture de módulo específico. Se representan, pero es necesario validar la salida visual antes de la aprobación para producción.
Sin árbol retenido. El motor de streaming (ADR-001) no mantiene ningún árbol de documento, por lo que no puede aplicar un selector donde un elemento hermano posterior vuelve a aplicar estilo a un elemento anterior. Los selectores independientes del orden tienen limitaciones.
Propiedad no admitida. Una propiedad no admitida se ignora; no se genera como error. Debe confirmarse en la matriz antes de depender de ella.
Espacios de color. Los valores Lab, LCH y OKLab se analizan, pero no se garantiza la fidelidad del espacio de color del PDF para esas funciones (matriz: «Claimed» para CSS Color 4).

Rendimiento

La resolución de la cascada forma parte de la pasada única. El coste se mantiene lineal respecto del número de tokens, O(n). El presupuesto es wall_ms: 1500, peak_mb: 96. Un bloque <style> añade un coste único de análisis de selectores proporcional al número de reglas.

Extracto de la matriz de compatibilidad de CSS (solo filas Verified)

Este extracto reproduce únicamente las filas Verified de la matriz de compatibilidad de CSS auditada con rigor.

Módulo del W3C	Nivel	Estado	Evidencia
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/` + pruebas de revert/layer
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/` + pruebas de FontResolver
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color y background-color son «Claimed» en la matriz. La tabla los excluye de las filas Verified de forma deliberada.

Restricciones del streaming de una sola pasada (ADR-001)

La cascada se ejecuta sobre una lista de tokens transmitida en streaming sin DOM, por lo que los selectores se resuelven según el contexto del orden del documento. Los casos de selectores de árbol completo tienen limitaciones según ADR-006. Es recomendable escribir CSS que dependa únicamente del orden del documento y del contexto de los antecesores.

Contratos de capa (ADR-010)

El análisis de CSS pertenece a la capa de cascada, y el envío de diseño no debe leer directamente los valores $css[...] sin procesar. La superficie pública es la entrada HTML. No existe ninguna forma admitida de inyectar estilos calculados más allá de la cascada.

Presupuesto de memoria para documentos grandes

La cascada conserva el conjunto de reglas activo y la pila de estilos de inserción y extracción, no un árbol de nodos. Los contextos con ámbito de contenedor respetan el presupuesto de ADR-020 (5,000 nodos por contexto, techo activo de 50 MB). Las hojas de estilo grandes aumentan la memoria del conjunto de reglas de forma lineal, por lo que conviene mantener acotado el número de selectores.

Notas de seguridad

El CSS en HTML no confiable no puede ejecutar código, pero sí puede afectar al diseño y a las referencias de recursos (por ejemplo, background-image). La política predeterminada de recursos externos no recupera URL remotas arbitrarias. Es necesario sanear todo el HTML y el CSS ensamblado a partir de la entrada del usuario antes de representarlo.

Conformidad

Afirmación	Especificación	Cláusula	reference_id
Las propiedades de texto (text-align, text-indent, letter-spacing) están definidas por la tabla de propiedades de CSS Text.	W3C CSS Text Level 3	css_text_3#x1.x24
La abreviatura font establece font-style, font-variant, font-weight, font-size y font-family.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Esta receta muestra cómo NextPDF aplica un subconjunto de CSS admitido; no afirma una compatibilidad total con CSS. Para conocer el estado verificado por módulo, consultar la matriz de compatibilidad de CSS.

Contexto comercial

No aplicable.