Estilizar HTML com CSS

Visão geral

Esta receita mostra como aplicar Cascading Style Sheets (CSS) a conteúdo em Hypertext Markup Language (HTML). Ela usa atributos style inline e um bloco <style>. Você também aprende a confirmar se o suporte a uma propriedade está comprovado antes de depender dela.

Instalação

composer require nextpdf/core:^3

Use essa restrição de versão para o pacote nextpdf/core. O exemplo é executado no PHP 8.4.

Visão conceitual

O mecanismo HTML resolve estilos por meio da cascata de CSS. A cascata decide qual estilo prevalece quando várias regras se aplicam ao mesmo elemento. O mecanismo lê primeiro o bloco <style> da entrada e, em seguida, os atributos style inline. Ele aplica ambos aos elementos e calcula o resultado na ordem da cascata. A matriz de suporte classifica o módulo CSS Cascading and Inheritance como Verified, o que significa que um conjunto dedicado de fixtures cobre o comportamento de cascata e herança.

Propriedades de apresentação de texto como text-align, text-indent e letter-spacing são definidas na tabela de propriedades do módulo CSS Text do World Wide Web Consortium (W3C) (W3C CSS Text Level 3). A seleção de fontes usa o modelo CSS Fonts. O atalho font define font-style, font-variant, font-weight, font-size e font-family em conjunto (W3C CSS Fonts Level 3).

O suporte é rastreado por módulo do W3C e auditado quanto à veracidade. Uma propriedade pode estar implementada e ainda assim não ter uma fixture de módulo dedicada; nesse caso, ela é classificada como “Claimed”, não “Verified”. Trate “Claimed” como melhor esforço e valide o resultado visual para o seu conteúdo. Trate “Verified” como respaldado por um conjunto de fixtures aprovado.

Superfície da API

Você controla a estilização por meio do HTML que passa para writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Não há uma API (application programming interface) separada para CSS; a cascata é executada internamente. A tabela PHPDoc completa é gerada a partir do código-fonte.

Exemplo de código — Início 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');

Exemplo de código — Produção

Este exemplo autocontido pode ser executado no harness. Ele exercita um bloco <style>, seletores de classe, estilos inline e o caminho de família e peso do atalho 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";

Saída padrão esperada (STDOUT):

Wrote style-with-css.pdf

Casos extremos & pegadinhas

Ordem da cascata. Na cascata, um style inline prevalece sobre um seletor de bloco <style> com a mesma especificidade. Se você notar uma cor inesperada, verifique primeiro se há uma substituição inline.
Claimed versus Verified. text-align, text-indent e color são classificadas como “Claimed” na matriz. Elas estão implementadas, mas não têm uma fixture de módulo dedicada. Essas propriedades são renderizadas, mas você deve validar a saída visual antes da aprovação final para produção.
Sem árvore retida. O mecanismo de streaming, descrito no Architecture Decision Record (ADR-001), não mantém nenhuma árvore de documento; portanto, não consegue aplicar um seletor em que um irmão posterior reestiliza um elemento anterior. Como resultado, seletores independentes da ordem são limitados.
Propriedade não suportada. Uma propriedade não suportada é ignorada, não gerada como erro. Verifique a matriz antes de depender dela.
Espaços de cor. Valores Lab, LCH e OKLab são analisados, mas a fidelidade do espaço de cor do Portable Document Format (PDF) para essas funções não é assegurada (matriz: “Claimed” para CSS Color 4).

Desempenho

A resolução da cascata acontece em uma única passagem. O custo permanece linear em relação à contagem de tokens, O(n). O orçamento é wall_ms: 1500, peak_mb: 96. Um bloco <style> adiciona um custo único de análise de seletores, proporcional à contagem de regras.

Trecho da matriz de suporte de CSS (apenas linhas Verified)

Este trecho mostra apenas as linhas Verified da matriz de suporte de CSS auditadas quanto à veracidade.

Módulo do W3C	Nível	Status	Evidência
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/` + testes de revert/layer
CSS Cascading (`css_cascade_5`)	5	Verified	`AtRule/Layer/` + `Cascade/Layer/` (conjuntos)
CSS Fonts (`css_fonts_3`)	3	Verified	`src/Html/Font/`, `tests/Unit/Font/` + testes do FontResolver
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color e background-color são “Claimed” na matriz. A tabela as omite deliberadamente das linhas Verified.

Restrições de streaming de passagem única (ADR-001)

A cascata é executada sobre uma lista de tokens transmitida sem Document Object Model (DOM); portanto, os seletores são resolvidos em relação ao contexto de ordem do documento. Os casos de seletor de árvore completa são limitados conforme o ADR-006. Escreva CSS que dependa apenas da ordem do documento e do contexto de ancestrais.

Contratos de camada (ADR-010)

A análise de CSS pertence à camada de cascata, e o despacho de layout não deve ler valores brutos de $css[...] diretamente. A superfície pública é a entrada HTML. Não há uma forma suportada de injetar estilos computados depois da cascata.

Orçamento de memória para documentos grandes

A cascata mantém o conjunto de regras ativo e a pilha de estilos de push e pop, não uma árvore de nós. Os contextos com escopo de contêiner obedecem ao orçamento do ADR-020 (5,000 nós por contexto, teto ativo de 50 MB). Folhas de estilo grandes aumentam a memória do conjunto de regras de forma linear; portanto, mantenha as contagens de seletores limitadas.

Notas de segurança

O CSS em HTML não confiável não pode executar código, mas pode afetar o layout e as referências de recursos, como background-image. A política padrão de recursos externos não busca URLs remotas arbitrárias. Faça a sanitização de todo o HTML e de todo o CSS que você montar a partir de entrada de usuário antes da renderização.

Conformidade

Declaração	Spec	Cláusula	reference_id
As propriedades de texto (text-align, text-indent, letter-spacing) são definidas pela tabela de propriedades CSS Text.	W3C CSS Text Level 3	css_text_3#x1.x24
O atalho font define font-style, font-variant, font-weight, font-size e font-family.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

Esta receita mostra como o NextPDF aplica um subconjunto suportado de CSS; ela não afirma suporte total a CSS. Para o status verificado por módulo, consulte a matriz de suporte de CSS.

Contexto comercial

Não aplicável.