estabilidad: Experimental

Indicadores de vista previa de CSS Paged Media (contenido en ejecución de GCPM, páginas con nombre, flotantes de página)

De un vistazo

Vista previa opcional. Estas cuatro características de CSS están desactivadas por defecto. Cuando el indicador está desactivado, el motor produce una salida idéntica byte a byte a la de una compilación que nunca conoció la característica. Active una característica solo cuando la necesite y valide el resultado con sus documentos.

El renderizador de HTML añade cuatro características opcionales de medios paginados de los módulos CSS Paged Media y Generated Content for Paged Media (GCPM). Cada una es un indicador independiente en CssFeatureFlags. Cada una lleva un límite honesto de cierre seguro: una construcción que el motor de una sola pasada no puede resolver con fidelidad se descarta o se degrada con un diagnóstico con nombre, y nunca se representa de forma incorrecta.

Característica	Indicador	Qué hace cuando está activada
Cadenas con nombre (GCPM)	`runningStrings`	Captura con `string-set` más `string()` en las cajas de margen de `@page`: encabezados y pies de página en ejecución.
Páginas con nombre (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, la propiedad `page:` y `:first` / `:left` / `:right` / `:blank`: cajas de margen y decoración por página.
Elementos en ejecución (GCPM)	`runningElements`	`position: running(<ident>)` más `content: element(<ident>)`: reproduce el texto de un elemento en una caja de margen.
Flotantes de página (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap`: mueve una caja a la banda superior o inferior de la página.

Instalación

composer require nextpdf/core:^3

Los indicadores se incluyen en el paquete core. La superficie pública de CssFeatureFlags es @since 6.1.0. La versión del motor (Version::VERSION) no cambia; estas características son aditivas y están desactivadas por defecto.

Panorama conceptual

El renderizador es de una sola pasada y por streaming (consulte ADR-001). No mantiene ningún árbol de documento y escribe la salida una sola vez en orden de documento. Esa restricción moldea cada característica de aquí. Cada característica resuelve lo que puede ver en una sola pasada hacia adelante y se cierra de forma segura ante cualquier cosa que necesitara una segunda pasada o un árbol retenido. El límite está documentado, no oculto: saber dónde se detiene una característica forma parte de su uso.

Habilita una característica construyendo CssFeatureFlags con el indicador puesto en true y pasándolo a Config. Cuando un indicador está desactivado, el CSS correspondiente se analiza y se ignora exactamente como lo haría una propiedad no admitida, de modo que la salida es idéntica byte a byte a una compilación sin la característica.

Cadenas con nombre — `runningStrings`

string-set: <ident> content() registra un valor a medida que el motor pasa por el elemento. Una referencia string(<ident>) dentro de una caja de margen de @page se resuelve entonces al valor más reciente visto en esa página. Este es el mecanismo estándar para un encabezado en ejecución que sigue el capítulo o la sección actual.

La resolución es de una sola pasada, “el último visto en esta página”. Una referencia string() se resuelve al último valor que el motor registró antes de componer las cajas de margen de esa página.

Límite de cierre seguro. Con el indicador desactivado, string() se resuelve a la cadena vacía y la salida permanece idéntica byte a byte. Una lista de contenido string-set mal formada descarta ese único par de asignación y continúa; nunca aborta la representación.

Páginas con nombre — `namedPagesAdvanced`

La propiedad page: <ident> asigna un elemento a un contexto de página con nombre, y una regla @page <ident> coincidente proporciona las cajas de margen y la decoración de página de ese contexto. Las pseudoclases de página :first, :left, :right y :blank seleccionan la primera página, las páginas recto y verso, y las páginas intencionadamente en blanco.

Esta característica selecciona las cajas de margen y la decoración de una página con nombre o pseudopágina. No cambia la geometría de la página.

Límite de cierre seguro. Una regla @page con nombre o pseudo que intente cambiar la geometría —size, rotate o un margen de caja de contenido que redimensione el área de página— se cierra de forma segura con UnsupportedNamedPageException en lugar de producir silenciosamente una página desalineada. El canal de coincidencia de pseudoclases es la primera porción; los casos de selector más amplios están diferidos y documentados.

Elementos en ejecución — `runningElements`

position: running(<ident>) retira un elemento del flujo normal y lo aparca bajo un nombre. content: element(<ident>) en una caja de margen reproduce entonces ese elemento en cada página. Úselo cuando un encabezado necesite el texto completo con estilo de un encabezamiento, no solo una cadena capturada.

Límite de cierre seguro. Esta porción reproduce solo el texto del elemento en ejecución. El contenido enriquecido —imágenes, elementos reemplazados, estructura de bloques anidada— se descarta, y el motor emite un diagnóstico HTML_RUNNING_ELEMENT_DEGRADED para que la pérdida sea visible, no silenciosa. Un elemento running() que se referencia a sí mismo, un running() anidado o una captura que excede el presupuesto interno se cierra de forma segura. Con el indicador desactivado, running() y element() son inertes.

Flotantes de página — `pageFloats`

float: top, float: bottom y float: snap mueven una caja a la banda superior o inferior de la página en el eje de bloque, reservando la altura de la banda para que el texto circundante refluya alrededor de la región reservada.

float: bottom (y snap cuando se resuelve a la banda inferior) es el caso que el motor de una sola pasada maneja directamente: la caja se captura y se coloca en la banda inferior de la página al cerrarse la página. float: top se reduce a la banda superior de la página.

Límite de cierre seguro. snap en el eje en línea (snap-inline) no se admite. Una caja que arrastra un efecto secundario inamovible —por ejemplo una anotación de enlace, cuyo rectángulo está ligado a su posición de flujo— no puede reubicarse con seguridad, por lo que vuelve al flujo normal y el motor emite un diagnóstico HTML_PAGE_FLOAT_* que explica el repliegue. Con el indicador desactivado, float: top | bottom | snap se trata como un valor no admitido y se ignora.

Superficie de la API

Símbolo	Ubicación	Función
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	Conjunto de indicadores opcionales inmutable; el constructor toma `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` (todos `false` por defecto).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Adjunta el conjunto de indicadores a la configuración de un documento.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	Resuelve un conjunto de indicadores para un modo de representación (el modo Safe fuerza la desactivación de todos los indicadores; el modo Normal usa el conjunto explícito, o `allEnabled()` cuando no se proporciona ninguno).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	Se lanza cuando una regla `@page` con nombre/pseudo cambia la geometría de la página.

Los códigos de advertencia de diagnóstico afloran a través del canal de avisos del resultado de la representación: HTML_RUNNING_ELEMENT_DEGRADED, la familia HTML_RUNNING_ELEMENT_* y la familia HTML_PAGE_FLOAT_*.

Ejemplo de código — Inicio rápido

Habilite las cadenas con nombre para un encabezado en ejecución que siga el capítulo actual.

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

Ejemplo de código — Producción

Habilite varios indicadores a la vez y trate el canal de avisos como una señal de que una construcción se degradó. Los indicadores son independientes; active solo los que use.

<?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 límite y trampas

Los cuatro indicadores son independientes y están desactivados por defecto. Un indicador desactivado produce una salida idéntica byte a byte. Active solo lo que use.
string() está vacío cuando runningStrings está desactivado, por diseño. No hay advertencia para el caso desactivado; es el valor predeterminado documentado.
Los elementos en ejecución reproducen solo texto. Las imágenes y los bloques anidados dentro de un elemento en ejecución se descartan con HTML_RUNNING_ELEMENT_DEGRADED. Revise el canal de avisos.
Las páginas con nombre no pueden cambiar la geometría. Una regla @page con nombre/pseudo que cambie la geometría lanza UnsupportedNamedPageException. Establezca el tamaño y la rotación de página a través de Config, no a través de una regla @page con nombre.
Los flotantes de página mantienen los enlaces en el flujo. Una caja flotante que contiene una anotación de enlace vuelve al flujo normal con un diagnóstico HTML_PAGE_FLOAT_*, porque el rectángulo del enlace está ligado a su posición de flujo.

Rendimiento

Cada característica añade una cantidad acotada de trabajo de una sola pasada: las cadenas con nombre registran un valor por elemento string-set; las páginas con nombre añaden una resolución de caja de margen por página; los elementos en ejecución capturan un búfer de texto por elemento aparcado; los flotantes de página reservan una banda por página. Ninguna retiene un árbol de documento, por lo que se preserva el modelo de memoria O(profundidad de anidamiento) del renderizador por streaming. El performance_budget por página (wall_ms: 1500, peak_mb: 64) no cambia.

Notas de seguridad

Estos indicadores no amplían la superficie de entrada. La política de seguridad de HTML, la lista de permitidos de propiedades CSS y los límites de bytes de la hoja de estilo y de anidamiento se aplican sin cambios. El contenido de cadenas y elementos capturado se escapa a través de la misma ruta de salida que cualquier otro texto. Las características añaden comportamiento de maquetación, no un nuevo canal de ingesta.

Conformidad

Afirmación	Especificación	Cláusula
`string-set` registra una cadena con nombre; `string()` la resuelve en una caja de margen de página.	W3C CSS Generated Content for Paged Media	§3
`position: running()` retira un elemento del flujo; `content: element()` lo reproduce.	W3C CSS Generated Content for Paged Media	§5
La propiedad `page` y `@page <ident>` seleccionan un contexto de página con nombre.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` flota una caja en el eje de bloque hacia una banda de página.	W3C CSS Page Floats Level 3	§5

Estas son implementaciones de vista previa de características de módulos en grupo de trabajo. NextPDF implementa un subconjunto de una sola pasada con los límites de cierre seguro documentados arriba. El estado verificado por propiedad se registra en la matriz de compatibilidad de CSS; aquí no se reclama ninguna conformidad de extremo a extremo. No se reproduce ningún texto de las normas.