Layout in modalità mantenuta per CSS Grid (grid-template-areas)

In sintesi

Anteprima opt-in. La modalità mantenuta è disattivata per impostazione predefinita. La modalità Streaming predefinita è byte-identica a una build che non ha mai conosciuto l’esistenza di questa modalità. Attivala solo per i documenti che necessitano di una vera griglia e convalida il risultato.

Per impostazione predefinita, il renderer è a passaggio singolo e in streaming (vedi ADR-001). Una griglia CSS Grid dichiarata con grid-template-areas non può essere collocata in un solo passaggio in avanti, perciò il motore in streaming emette un avviso HTML_GRID_REQUIRES_RETAINED e ricade nel flusso a blocco. La modalità mantenuta è l’opt-in che sostituisce quel fallback con un layout reale: Config::withCssLayoutMode(CssLayoutMode::Retained) instrada una griglia grid-template-areas a colonne definite attraverso il GridLayoutEngine, che colloca i figli nelle loro celle nominate.

Installazione

composer require nextpdf/core:^3

La modalità di layout è inclusa nel pacchetto core. L’opt-in Config::withCssLayoutMode è @since 6.0.0. L’impostazione predefinita resta CssLayoutMode::Streaming.

Panoramica concettuale

CssLayoutMode è un enum tipizzato su Config. Streaming è l’impostazione predefinita e il comportamento storico; Retained fa optare un documento nel motore di griglia. La modalità mantenuta conserva un insieme limitato di nodi mantenuti (il retainedNodeBudget, predefinito 50,000, vincolato a [5,000, 100,000]) affinché il motore possa risolvere una griglia che lo streaming non può — senza abbandonare la disciplina di memoria del motore.

Quando la modalità mantenuta è attiva e il motore incontra una griglia grid-template-areas le cui colonne sono definite, la dispone realmente. Le colonne definite sono lunghezze fisse, percentuali o unità fr risolte rispetto alla larghezza del contenuto. Le righe fluiscono automaticamente. I figli vengono assegnati alle celle che selezionano i nomi delle loro aree.

ADR-001 registra l’invariante dello streaming. La modifica del 2026-06-28 a ADR-001 aggiunge un’eccezione ritagliata per l’opt-in mantenuto: l’impostazione predefinita in streaming resta intatta e mantiene il modello a passaggio singolo; la modalità mantenuta è un’eccezione opt-in, esplicitamente limitata, per il caso della griglia.

Confine — cosa dispone la modalità mantenuta e cosa ancora ricade nel fallback

La modalità mantenuta gestisce il caso grid-template-areas a colonne definite e solo quel caso. Tutto ciò che ne è al di fuori mantiene l’avviso HTML_GRID_REQUIRES_RETAINED e il fallback a blocco, anche con la modalità mantenuta attiva:

• grid-auto-flow: column e grid-auto-flow: dense.
• subgrid.
• Le query @container.
• Le tracce di colonna automatiche o intrinseche (auto, min-content, max-content).

Queste sono fette rinviate, non lacune silenziose. Una griglia che dipende da una di esse degrada al flusso a blocco e te lo comunica.

Confine fail-closed. Una discrepanza tra acquisizione e motore — la larghezza del contenuto misurata che diverge dalla larghezza rispetto a cui il motore di griglia risolve — fallisce in modo fail-closed invece di produrre una griglia collocata in modo errato. La modalità mantenuta è inoltre incompatibile con la modalità di rendering CSS Safe: CssRenderingMode::Safe combinata con CssLayoutMode::Retained solleva IncompatibleRenderingModeException alla convalida della configurazione. CssLayoutMode::Auto è riservato e solleva NotImplementedException.

Superficie API

Simbolo	Posizione	Ruolo
Config::withCssLayoutMode(CssLayoutMode $mode): self	src/Core/Config.php	Fa optare un documento nel layout Streaming (predefinito) o Retained.
Config::withRetainedNodeBudget(int $budget): self	src/Core/Config.php	Limita l’insieme di nodi mantenuti ([5,000, 100,000], predefinito 50,000).
Config::isRetainedMode(): bool	src/Core/Config.php	Segnala se il documento è in modalità mantenuta.
CssLayoutMode	src/Core/	Streaming, Retained; Auto riservato (NotImplementedException).
GridLayoutEngine	src/Html/	Il motore di collocazione della griglia mantenuta.
IncompatibleRenderingModeException	src/Exception/	Sollevata quando la modalità CSS Safe è combinata con la modalità mantenuta.

Esempio di codice — Avvio rapido

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

Esempio di codice — Produzione

Rileva il caso di modalità incompatibile al momento della configurazione e rileggi la modalità attiva affinché il percorso sia esplicito.

<?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.

Casi limite e insidie

• Lo Streaming resta l’impostazione predefinita ed è byte-identico. La modalità mantenuta cambia l’output solo per il documento per cui fai opt-in.
• Solo grid-template-areas a colonne definite. L’auto-flow di colonna, il dense packing, subgrid, @container e le colonne intrinseche mantengono l’avviso HTML_GRID_REQUIRES_RETAINED e il fallback a blocco.
• La modalità Safe è mutuamente esclusiva. CssRenderingMode::Safe più CssLayoutMode::Retained solleva IncompatibleRenderingModeException.
• Auto è riservato. CssLayoutMode::Auto solleva NotImplementedException; non è ancora una terza opzione utilizzabile.
• La discrepanza di larghezza fallisce in modo fail-closed. Un disaccordo di larghezza del contenuto tra acquisizione e motore viene rifiutato, non reso in modo errato.

Prestazioni

La modalità mantenuta conserva un insieme limitato di nodi anziché un albero completo del documento; il retainedNodeBudget (predefinito 50,000) lo limita. La collocazione della griglia è lineare nel conteggio dei nodi e delle celle. Il performance_budget per pagina (wall_ms: 1500, peak_mb: 64) si applica; per le griglie grandi è bene tenere a mente il budget quando si alza il budget dei nodi verso il suo tetto di 100,000.

Note sulla sicurezza

La modalità mantenuta non amplia la superficie di input. La policy di sicurezza HTML, l’allowlist delle proprietà CSS e i limiti del parser si applicano invariati. Il budget dei nodi mantenuti è esso stesso un limite contro l’esaurimento delle risorse: limita quanta struttura il motore conserverà per un singolo documento.

Conformità

Affermazione	Standard	Clausola
grid-template-areas nomina le celle della griglia; le aree nominate collocano gli elementi.	W3C CSS Grid Layout Module Level 1	§7.3
Le tracce esplicite fisse, percentuali e fr si dimensionano rispetto alla larghezza del contenuto.	W3C CSS Grid Layout Module Level 1	§7.2

Questa è un’implementazione di anteprima di un sottoinsieme grid-template-areas a colonne definite. Lo stato verificato per ogni proprietà è tracciato nella matrice di supporto CSS; qui non si rivendica alcuna conformità end-to-end. Nessun testo normativo è riprodotto.

Vedere anche

• Sottosistema di rendering HTML
• Vincoli dello streaming a passaggio singolo (ADR-001)
• Flag di anteprima CSS dei paged-media
• Modulo Config
• Matrice di supporto CSS