estabilidad: Experimental

Maquetación en modo retenido para CSS Grid (grid-template-areas)

De un vistazo

Vista previa opcional. El modo retenido está desactivado por defecto. El modo Streaming predeterminado es idéntico byte a byte a una compilación que nunca conoció este modo. Actívelo solo para los documentos que necesitan una cuadrícula real y valide el resultado.

Por defecto, el renderizador es de una sola pasada y por streaming (consulte ADR-001). Una cuadrícula CSS Grid declarada con grid-template-areas no puede colocarse en una sola pasada hacia adelante, por lo que el motor de streaming emite una advertencia HTML_GRID_REQUIRES_RETAINED y repliega a flujo de bloque. El modo retenido es la opción que reemplaza ese repliegue por una maquetación real: Config::withCssLayoutMode(CssLayoutMode::Retained) enruta una cuadrícula grid-template-areas de columnas definidas a través del GridLayoutEngine, que coloca los hijos en sus celdas con nombre.

Instalación

composer require nextpdf/core:^3

El modo de maquetación se incluye en el paquete core. La opción Config::withCssLayoutMode es @since 6.0.0. El valor predeterminado sigue siendo CssLayoutMode::Streaming.

Panorama conceptual

CssLayoutMode es una enumeración tipada en Config. Streaming es el valor predeterminado y el comportamiento histórico; Retained opta un documento por el motor de cuadrícula. El modo retenido mantiene un conjunto acotado de nodos retenidos (el retainedNodeBudget, 50,000 por defecto, restringido a [5,000, 100,000]) para que el motor pueda resolver una cuadrícula que el streaming no puede, sin abandonar la disciplina de memoria del motor.

Cuando el modo retenido está activado y el motor encuentra una cuadrícula grid-template-areas cuyas columnas son definidas, la dispone de verdad. Las columnas definidas son longitudes fijas, porcentajes o unidades fr resueltas frente al ancho del contenido. Las filas fluyen automáticamente. Los hijos se asignan a las celdas que seleccionan sus nombres de área.

ADR-001 registra el invariante de streaming. La enmienda del 2026-06-28 a ADR-001 añade una excepción opcional de modo retenido: el valor predeterminado de streaming permanece intacto y conserva el modelo de una sola pasada; el modo retenido es una excepción opcional, explícitamente acotada, para el caso de la cuadrícula.

Límite — qué dispone el modo retenido y qué sigue replegándose

El modo retenido maneja el caso grid-template-areas de columnas definidas y solo ese caso. Todo lo que queda fuera conserva la advertencia HTML_GRID_REQUIRES_RETAINED y el repliegue de bloque, incluso con el modo retenido activado:

grid-auto-flow: column y grid-auto-flow: dense.
subgrid.
Consultas @container.
Pistas de columna automáticas o intrínsecas (auto, min-content, max-content).

Estas son porciones diferidas, no vacíos silenciosos. Una cuadrícula que depende de una de ellas se degrada a flujo de bloque y se lo indica.

Límite de cierre seguro. Un desajuste entre la captura y el motor —el ancho del contenido medido difiriendo del ancho frente al que resuelve el motor de cuadrícula— se cierra de forma segura en lugar de producir una cuadrícula mal colocada. El modo retenido también es incompatible con el modo de representación Safe de CSS: CssRenderingMode::Safe combinado con CssLayoutMode::Retained lanza IncompatibleRenderingModeException en la validación de la configuración. CssLayoutMode::Auto está reservado y lanza NotImplementedException.

Superficie de la API

Símbolo	Ubicación	Función
`Config::withCssLayoutMode(CssLayoutMode $mode): self`	`src/Core/Config.php`	Opta un documento por la maquetación `Streaming` (por defecto) o `Retained`.
`Config::withRetainedNodeBudget(int $budget): self`	`src/Core/Config.php`	Acota el conjunto de nodos retenidos (`[5,000, 100,000]`, `50,000` por defecto).
`Config::isRetainedMode(): bool`	`src/Core/Config.php`	Informa de si el documento está en modo retenido.
`CssLayoutMode`	`src/Core/`	`Streaming`, `Retained`; `Auto` reservado (`NotImplementedException`).
`GridLayoutEngine`	`src/Html/`	El motor de colocación de cuadrícula retenida.
`IncompatibleRenderingModeException`	`src/Exception/`	Se lanza cuando el modo Safe de CSS se combina con el modo retenido.

Ejemplo de código — Inicio rápido

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\CssLayoutMode;
use NextPDF\Core\Document;

$config = (new Config())->withCssLayoutMode(CssLayoutMode::Retained);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<style>'
    . '.dashboard { display: grid; grid-template-columns: 1fr 2fr;'
    . '  grid-template-areas: "sidebar main"; }'
    . '.sidebar { grid-area: sidebar; } .main { grid-area: main; }'
    . '</style>'
    . '<div class="dashboard">'
    . '  <div class="sidebar">Navigation</div>'
    . '  <div class="main">Report content…</div>'
    . '</div>',
);
$doc->save(__DIR__ . '/grid.pdf');

Ejemplo de código — Producción

Detecte el caso de modo incompatible en el momento de la configuración y vuelva a leer el modo activo para que la ruta sea explícita.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\CssLayoutMode;
use NextPDF\Core\Document;
use NextPDF\Exception\IncompatibleRenderingModeException;

try {
    $config = (new Config())
        ->withCssLayoutMode(CssLayoutMode::Retained)
        ->withRetainedNodeBudget(75_000);
    $config->validate();
} catch (IncompatibleRenderingModeException $e) {
    // Safe CSS mode and retained mode cannot combine. Choose one.
    throw $e;
}

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

$doc->addPage();
$doc->writeHtml($gridHtml);
$doc->save($out);

// A grid that needs a deferred feature (column auto-flow, subgrid, @container,
// or intrinsic columns) still emits HTML_GRID_REQUIRES_RETAINED and falls back
// to block flow. Inspect the advisory channel.

Casos límite y trampas

Streaming sigue siendo el predeterminado y es idéntico byte a byte. El modo retenido cambia la salida solo para el documento que usted opta.
Solo grid-template-areas de columnas definidas. El flujo automático de columnas, el empaquetado denso, subgrid, @container y las columnas intrínsecas conservan la advertencia HTML_GRID_REQUIRES_RETAINED y el repliegue de bloque.
El modo Safe es mutuamente excluyente. CssRenderingMode::Safe más CssLayoutMode::Retained lanza IncompatibleRenderingModeException.
Auto está reservado. CssLayoutMode::Auto lanza NotImplementedException; todavía no es una tercera opción utilizable.
El desajuste de ancho se cierra de forma segura. Una discrepancia de ancho de contenido entre la captura y el motor se rechaza, no se representa de forma incorrecta.

Rendimiento

El modo retenido mantiene un conjunto acotado de nodos en lugar de un árbol de documento completo; el retainedNodeBudget (50,000 por defecto) lo limita. La colocación de la cuadrícula es lineal en el recuento de nodos y celdas. Se aplica el performance_budget por página (wall_ms: 1500, peak_mb: 64); las cuadrículas grandes deben tener en cuenta el presupuesto al elevar el presupuesto de nodos hacia su techo de 100,000.

Notas de seguridad

El modo retenido no amplía la superficie de entrada. La política de seguridad de HTML, la lista de permitidos de propiedades CSS y los límites del analizador se aplican sin cambios. El presupuesto de nodos retenidos es en sí mismo un límite de agotamiento de recursos: limita cuánta estructura mantendrá el motor para un solo documento.

Conformidad

Afirmación	Especificación	Cláusula
`grid-template-areas` nombra las celdas de la cuadrícula; las áreas con nombre colocan los elementos.	W3C CSS Grid Layout Module Level 1	§7.3
Las pistas fijas, de porcentaje y `fr` explícitas se dimensionan frente al ancho del contenido.	W3C CSS Grid Layout Module Level 1	§7.2

Esta es una implementación de vista previa de un subconjunto grid-template-areas de columnas definidas. 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.