estabilidade: Experimental

Flags de pré-visualização de CSS Paged Media (conteúdo corrente GCPM, páginas nomeadas, page floats)

Visão geral

Pré-visualização opcional. Esses quatro recursos CSS são desativados por padrão. Quando a flag está desativada, o motor produz uma saída idêntica byte a byte à de uma compilação que nunca soube que o recurso existia. Ative um recurso somente quando quiser e valide o resultado para os seus documentos.

O renderizador HTML adiciona quatro recursos opcionais de paged media dos módulos CSS Paged Media e Generated Content for Paged Media (GCPM). Cada um é uma flag separada em CssFeatureFlags. Cada um carrega um limite honesto de falha fechada: uma construção que o motor de passada única não consegue resolver fielmente é descartada ou degradada com um diagnóstico nomeado, nunca renderizada de forma incorreta.

Recurso	Flag	O que faz quando ativado
Strings nomeadas (GCPM)	`runningStrings`	Captura de `string-set` mais `string()` em margin boxes de `@page` — cabeçalhos e rodapés correntes.
Páginas nomeadas (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, a propriedade `page:` e `:first` / `:left` / `:right` / `:blank` — margin boxes e decoração por página.
Elementos correntes (GCPM)	`runningElements`	`position: running(<ident>)` mais `content: element(<ident>)` — repete o texto de um elemento em uma margin box.
Page floats (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — move uma caixa para a faixa superior ou inferior da página.

Instalação

composer require nextpdf/core:^3

As flags são entregues no pacote core. A superfície pública de CssFeatureFlags é @since 6.1.0. A versão do motor (Version::VERSION) permanece inalterada; esses recursos são aditivos e desativados por padrão.

Visão geral conceitual

O renderizador é de passada única e em streaming (consulte ADR-001). Ele não mantém nenhuma árvore de documento e grava a saída uma única vez, na ordem do documento. Essa restrição molda cada recurso desta página. Cada recurso resolve o que consegue enxergar em uma única passada para frente e falha fechada em qualquer coisa que exigiria uma segunda passada ou uma árvore retida. O limite é documentado, não oculto — saber onde um recurso para faz parte de usá-lo.

Você ativa um recurso construindo CssFeatureFlags com a flag definida como true e passando-a para Config. Quando uma flag está desativada, o CSS correspondente é analisado e ignorado exatamente como seria uma propriedade não suportada, de modo que a saída é idêntica byte a byte à de uma compilação sem o recurso.

Strings nomeadas — `runningStrings`

string-set: <ident> content() registra um valor à medida que o motor passa pelo elemento. Uma referência string(<ident>) dentro de uma margin box de @page então resolve para o valor mais recente visto naquela página. Esse é o mecanismo padrão para um cabeçalho corrente que acompanha o capítulo ou a seção atual.

A resolução é de passada única, “último visto nesta página”. Uma referência string() resolve para o último valor que o motor registrou antes de dispor as margin boxes daquela página.

Limite de falha fechada. Com a flag desativada, string() resolve para a string vazia e a saída permanece idêntica byte a byte. Uma lista de conteúdo string-set malformada descarta aquele único par de atribuição e continua; ela nunca aborta a renderização.

Páginas nomeadas — `namedPagesAdvanced`

A propriedade page: <ident> atribui um elemento a um contexto de página nomeada, e uma regra @page <ident> correspondente fornece as margin boxes e a decoração de página daquele contexto. As pseudoclasses de página :first, :left, :right e :blank selecionam a primeira página, as páginas reto e verso e as páginas intencionalmente em branco.

Esse recurso seleciona as margin boxes e a decoração de uma página nomeada ou pseudo. Ele não altera a geometria da página.

Limite de falha fechada. Uma regra @page nomeada ou pseudo que tenta alterar a geometria — size, rotate ou uma margem de content-box que redimensiona a área da página — falha fechada com UnsupportedNamedPageException em vez de produzir silenciosamente uma página desalinhada. O canal de correspondência de pseudoclasses é a primeira fatia; casos de seletor mais amplos estão adiados e documentados.

Elementos correntes — `runningElements`

position: running(<ident>) remove um elemento do fluxo normal e o estaciona sob um nome. content: element(<ident>) em uma margin box então repete aquele elemento em cada página. Use quando um cabeçalho precisar do texto estilizado completo de um título, não apenas de uma string capturada.

Limite de falha fechada. Esta fatia repete apenas o texto do elemento corrente. Conteúdo rico — imagens, elementos substituídos, estrutura de bloco aninhada — é descartado, e o motor emite um diagnóstico HTML_RUNNING_ELEMENT_DEGRADED para que a perda seja visível, não silenciosa. Um elemento running() que referencia a si mesmo, um running() aninhado ou uma captura que excede o orçamento interno falha fechada. Com a flag desativada, running() e element() ficam inertes.

Page floats — `pageFloats`

float: top, float: bottom e float: snap movem uma caixa para a faixa superior ou inferior da página no eixo de bloco, reservando a altura da faixa para que o texto ao redor reflua em torno da região reservada.

float: bottom (e snap resolvendo para a faixa inferior) é o caso que o motor de passada única trata diretamente: a caixa é capturada e posicionada na faixa inferior da página à medida que a página é fechada. float: top degenera para a faixa do topo da página.

Limite de falha fechada. snap no eixo inline (snap-inline) não é suportado. Uma caixa que carrega um efeito colateral não móvel — por exemplo uma anotação de link, cujo retângulo está vinculado à sua posição de fluxo — não pode ser realocada com segurança, então ela recai para o fluxo normal e o motor emite um diagnóstico HTML_PAGE_FLOAT_* explicando o fallback. Com a flag desativada, float: top | bottom | snap é tratado como um valor não suportado e ignorado.

Superfície da API

Símbolo	Localização	Função
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	Conjunto imutável de flags opcionais; o construtor recebe `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` (todas `false` por padrão).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Anexa o conjunto de flags a uma configuração de documento.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	Resolve um conjunto de flags para um modo de renderização (o modo Safe força todas as flags desativadas; o modo Normal usa o conjunto explícito, ou `allEnabled()` quando nenhum é fornecido).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	Lançada quando uma regra `@page` nomeada/pseudo altera a geometria da página.

Os códigos de aviso de diagnóstico aparecem por meio do canal de advertências do resultado de renderização: HTML_RUNNING_ELEMENT_DEGRADED, a família HTML_RUNNING_ELEMENT_* e a família HTML_PAGE_FLOAT_*.

Exemplo de código — Início rápido

Ative strings nomeadas para um cabeçalho corrente que acompanha o capítulo atual.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(runningStrings: true),
);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<style>'
    . 'h2 { string-set: chapter content(); }'
    . '@page { @top-center { content: string(chapter); } }'
    . '</style>'
    . '<h2>Introduction</h2><p>Body text…</p>',
);
$doc->save(__DIR__ . '/running-header.pdf');

Exemplo de código — Produção

Ative várias flags em conjunto e trate o canal de advertências como um sinal de que uma construção foi degradada. As flags são independentes; ative apenas as que você usa.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Exception\UnsupportedNamedPageException;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(new CssFeatureFlags(
    runningStrings: true,
    namedPagesAdvanced: true,
    runningElements: true,
    pageFloats: true,
));

$doc = Document::createStandalone($config);
$doc->addPage();

try {
    $doc->writeHtml($html);
} catch (UnsupportedNamedPageException $e) {
    // A named @page rule tried to change page geometry (size/rotate/margin).
    // The engine fails closed rather than emit a misaligned page.
    throw $e;
}

$doc->save($out);

// Inspect $doc's advisory channel for HTML_RUNNING_ELEMENT_DEGRADED and
// HTML_PAGE_FLOAT_* before treating the output as final.

Casos extremos e pegadinhas

As quatro flags são independentes e desativadas por padrão. Uma flag desativada gera saída idêntica byte a byte. Ative apenas o que você usar.
string() fica vazia quando runningStrings está desativada, por projeto. Não há aviso para o caso desativado; esse é o padrão documentado.
Elementos correntes repetem apenas texto. Imagens e blocos aninhados dentro de um elemento corrente são descartados com HTML_RUNNING_ELEMENT_DEGRADED. Verifique o canal de advertências.
Páginas nomeadas não podem alterar a geometria. Uma regra @page nomeada/pseudo que altera a geometria lança UnsupportedNamedPageException. Defina o tamanho e a rotação da página por meio de Config, não por uma regra @page nomeada.
Page floats mantêm os links no fluxo. Uma caixa flutuada que contém uma anotação de link recai para o fluxo normal com um diagnóstico HTML_PAGE_FLOAT_*, porque o retângulo do link está vinculado à sua posição de fluxo.

Desempenho

Cada recurso adiciona uma quantidade limitada de trabalho de passada única: strings nomeadas registram um valor por elemento string-set; páginas nomeadas adicionam uma resolução de margin box por página; elementos correntes capturam um buffer de texto por elemento estacionado; page floats reservam uma faixa por página. Nenhum retém uma árvore de documento, então o modelo de memória O(profundidade de aninhamento) do renderizador em streaming é preservado. O performance_budget por página (wall_ms: 1500, peak_mb: 64) permanece inalterado.

Notas de segurança

Essas flags não ampliam a superfície de entrada. A política de segurança HTML, a allowlist de propriedades CSS e os limites de bytes de folha de estilo e de aninhamento se aplicam inalterados. O conteúdo de string e de elemento capturado é escapado pelo mesmo caminho de saída de qualquer outro texto. Os recursos adicionam comportamento de layout, não um novo canal de ingestão.

Conformidade

Declaração	Especificação	Cláusula
`string-set` registra uma string nomeada; `string()` a resolve em uma margin box de página.	W3C CSS Generated Content for Paged Media	§3
`position: running()` remove um elemento do fluxo; `content: element()` o repete.	W3C CSS Generated Content for Paged Media	§5
A propriedade `page` e `@page <ident>` selecionam um contexto de página nomeada.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` flutua uma caixa no eixo de bloco para uma faixa de página.	W3C CSS Page Floats Level 3	§5

Estas são implementações de pré-visualização de recursos de módulos do grupo de trabalho. O NextPDF implementa um subconjunto de passada única com os limites de falha fechada documentados acima. O status verificado por propriedade é acompanhado na matriz de suporte CSS; nenhuma conformidade de ponta a ponta é reivindicada aqui. Nenhum texto de norma é reproduzido.