Układ w trybie zachowanym dla CSS Grid (grid-template-areas)

W skrócie

Opcjonalny podgląd. Tryb zachowany jest domyślnie wyłączony. Domyślny tryb Streaming jest bajtowo identyczny z kompilacją, która nigdy nie znała tego trybu. Włączaj go tylko dla dokumentów wymagających prawdziwej siatki i waliduj wynik.

Domyślnie renderer jest jednoprzebiegowy i strumieniowy (zob. ADR-001). Siatki CSS zadeklarowanej przez grid-template-areas nie da się umieścić w jednym przebiegu naprzód, więc silnik strumieniowy emituje ostrzeżenie HTML_GRID_REQUIRES_RETAINED i wraca do przepływu blokowego. Tryb zachowany to opcja, która zastępuje to wycofanie prawdziwym układem: Config::withCssLayoutMode(CssLayoutMode::Retained) kieruje siatkę grid-template-areas o określonych kolumnach przez GridLayoutEngine, który umieszcza dzieci w ich nazwanych komórkach.

Instalacja

composer require nextpdf/core:^3

Tryb układu jest dostarczany w pakiecie core. Opcja Config::withCssLayoutMode to @since 6.0.0. Wartością domyślną pozostaje CssLayoutMode::Streaming.

Przegląd koncepcyjny

CssLayoutMode to typowany enum w Config. Streaming jest domyślny i stanowi historyczne zachowanie; Retained włącza dla dokumentu silnik siatki. Tryb zachowany utrzymuje ograniczony zachowany zbiór węzłów (retainedNodeBudget, domyślnie 50,000, przycięty do [5,000, 100,000]), dzięki czemu silnik może rozwiązać siatkę, której strumieniowanie nie potrafi — bez porzucania dyscypliny pamięciowej silnika.

Gdy tryb zachowany jest włączony, a silnik napotyka siatkę grid-template-areas, której kolumny są określone, rozkłada ją naprawdę. Kolumny określone to stałe długości, procenty lub jednostki fr rozwiązywane względem szerokości treści. Wiersze płyną automatycznie. Dzieci są przypisywane do komórek wybranych przez nazwy ich obszarów.

ADR-001 utrwala niezmiennik strumieniowania. Poprawka z 2026-06-28 do ADR-001 dodaje wyłączenie opcjonalne dla trybu zachowanego: domyślne strumieniowanie pozostaje nietknięte i wciąż jest modelem jednoprzebiegowym; tryb zachowany to jawnie ograniczony, opcjonalny wyjątek dla przypadku siatki.

Granica — co rozkłada tryb zachowany, a co wciąż się wycofuje

Tryb zachowany obsługuje przypadek grid-template-areas o określonych kolumnach i tylko ten przypadek. Wszystko poza nim zachowuje ostrzeżenie HTML_GRID_REQUIRES_RETAINED i wycofanie do bloku, nawet przy włączonym trybie zachowanym:

• grid-auto-flow: column oraz grid-auto-flow: dense.
• subgrid.
• Zapytania @container.
• Automatyczne lub samoistne ścieżki kolumn (auto, min-content, max-content).

To odroczone warstwy, a nie ciche luki. Siatka zależna od którejś z nich degraduje się do przepływu blokowego i informuje o tym.

Granica fail-closed. Niezgodność szerokości przechwytu względem silnika — zmierzona szerokość treści różniąca się od szerokości, względem której rozwiązuje silnik siatki — kończy się niepowodzeniem fail-closed, zamiast wytworzyć źle umieszczoną siatkę. Tryb zachowany jest też niezgodny z trybem renderowania Safe CSS: CssRenderingMode::Safe połączony z CssLayoutMode::Retained zgłasza IncompatibleRenderingModeException przy walidacji konfiguracji. CssLayoutMode::Auto jest zarezerwowany i zgłasza NotImplementedException.

Powierzchnia API

Symbol	Lokalizacja	Rola
Config::withCssLayoutMode(CssLayoutMode $mode): self	src/Core/Config.php	Włącza dla dokumentu układ Streaming (domyślny) lub Retained.
Config::withRetainedNodeBudget(int $budget): self	src/Core/Config.php	Ogranicza zachowany zbiór węzłów ([5,000, 100,000], domyślnie 50,000).
Config::isRetainedMode(): bool	src/Core/Config.php	Zgłasza, czy dokument jest w trybie zachowanym.
CssLayoutMode	src/Core/	Streaming, Retained; Auto zarezerwowany (NotImplementedException).
GridLayoutEngine	src/Html/	Silnik rozmieszczania siatki w trybie zachowanym.
IncompatibleRenderingModeException	src/Exception/	Zgłaszany, gdy tryb Safe CSS jest połączony z trybem zachowanym.

Przykład kodu — szybki start

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

Przykład kodu — produkcja

Wykryj przypadek niezgodnego trybu w czasie konfiguracji i odczytaj aktywny tryb, aby ścieżka była jawna.

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

Przypadki brzegowe i pułapki

• Streaming pozostaje domyślny i jest bajtowo identyczny. Tryb zachowany zmienia wynik tylko dla dokumentu, dla którego go włączysz.
• Tylko grid-template-areas o określonych kolumnach. Automatyczny przepływ kolumn, gęste upakowanie, subgrid, @container oraz kolumny samoistne zachowują ostrzeżenie HTML_GRID_REQUIRES_RETAINED i wycofanie do bloku.
• Tryb Safe wyklucza się wzajemnie. CssRenderingMode::Safe plus CssLayoutMode::Retained zgłasza IncompatibleRenderingModeException.
• Auto jest zarezerwowany. CssLayoutMode::Auto zgłasza NotImplementedException; nie jest to jeszcze użyteczna trzecia opcja.
• Niezgodność szerokości kończy się niepowodzeniem fail-closed. Rozbieżność szerokości treści przechwytu względem silnika jest odrzucana, a nie renderowana błędnie.

Wydajność

Tryb zachowany utrzymuje ograniczony zbiór węzłów, a nie pełne drzewo dokumentu; retainedNodeBudget (domyślnie 50,000) go ogranicza. Rozmieszczanie siatki jest liniowe względem liczby węzłów i komórek. Obowiązuje budżet performance_budget na stronę (wall_ms: 1500, peak_mb: 64); przy podnoszeniu budżetu węzłów ku jego górnej granicy 100,000 duże siatki powinny mieć ten budżet na uwadze.

Uwagi dotyczące bezpieczeństwa

Tryb zachowany nie poszerza powierzchni wejściowej. Polityka bezpieczeństwa HTML, lista dozwolonych właściwości CSS oraz limity parsera obowiązują bez zmian. Budżet zachowanych węzłów sam w sobie jest granicą wyczerpania zasobów: ogranicza, ile struktury silnik utrzyma dla pojedynczego dokumentu.

Zgodność

Twierdzenie	Norma	Klauzula
grid-template-areas nazywa komórki siatki; nazwane obszary rozmieszczają elementy.	W3C CSS Grid Layout Module Level 1	§7.3
Jawne ścieżki stałe, procentowe i fr są wymiarowane względem szerokości treści.	W3C CSS Grid Layout Module Level 1	§7.2

To podglądowa implementacja podzbioru grid-template-areas o określonych kolumnach. Status zweryfikowania poszczególnych właściwości jest śledzony w macierzy wsparcia CSS; nie deklaruje się tu zgodności end-to-end. Nie odtwarza się żadnego tekstu normatywnego.

Zobacz także

• Podsystem renderowania HTML
• Ograniczenia strumieniowania jednoprzebiegowego (ADR-001)
• Flagi podglądowe CSS Paged-media
• Moduł Config
• Macierz wsparcia CSS