CSS Grid için korunan kip yerleşimi (grid-template-areas)

Bir bakışta

Katılımlı önizleme. Korunan kip varsayılan olarak kapalıdır. Varsayılan Streaming kipi, bu kipin var olduğunu hiç bilmeyen bir derlemeyle bayt düzeyinde özdeştir. Bunu yalnızca gerçek bir grid’e ihtiyaç duyan belgeler için açın ve sonucu doğrulayın.

İşleyici varsayılan olarak tek geçişli ve akıştır (bkz. ADR-001). grid-template-areas ile bildirilen bir CSS Grid tek bir ileri geçişte yerleştirilemez; bu nedenle akış motoru bir HTML_GRID_REQUIRES_RETAINED uyarısı yayar ve blok akışına geri döner. Korunan kip, o geri dönüşü gerçek bir yerleşimle değiştiren katılımlı seçenektir: Config::withCssLayoutMode(CssLayoutMode::Retained), belirli sütunlu bir grid-template-areas grid’ini, çocukları adlandırılmış hücrelerine yerleştiren GridLayoutEngine üzerinden yönlendirir.

Kurulum

composer require nextpdf/core:^3

Yerleşim kipi core paketiyle birlikte gelir. Config::withCssLayoutMode katılımı @since 6.0.0 şeklindedir. Varsayılan, CssLayoutMode::Streaming olarak kalır.

Kavramsal genel bakış

CssLayoutMode, Config üzerinde türlenmiş bir enum’dur. Streaming varsayılan ve geçmişteki davranıştır; Retained bir belgeyi grid motoruna dahil eder. Korunan kip, sınırlı bir korunan düğüm kümesi tutar (retainedNodeBudget, varsayılan 50,000, [5,000, 100,000] aralığına sıkıştırılır); böylece motor, akışın çözemediği bir grid’i — motorun bellek disiplininden vazgeçmeden — çözebilir.

Korunan kip açıkken ve motor, sütunları belirli olan bir grid-template-areas grid’iyle karşılaştığında, grid’i gerçek anlamda yerleştirir. Belirli sütunlar, içerik genişliğine göre çözümlenen sabit uzunluklar, yüzdeler ya da fr birimleridir. Satırlar otomatik olarak akar. Çocuklar, alan adlarının seçtiği hücrelere atanır.

ADR-001, akış değişmezini kayda geçirir. ADR-001 belgesine 2026-06-28 tarihli ek, katılımlı bir korunan istisna sağlar: akış varsayılanına dokunulmaz ve tek geçişli model olarak kalır; korunan kip, grid durumu için açıkça sınırlandırılmış, katılımlı bir istisnadır.

Sınır — korunan kipin neyi yerleştirdiği ve neyin hâlâ geri döndüğü

Korunan kip, belirli sütunlu grid-template-areas durumunu ve yalnızca o durumu işler. Bunun dışındaki her şey, korunan kip açıkken bile HTML_GRID_REQUIRES_RETAINED uyarısını ve blok geri dönüşünü korur:

• grid-auto-flow: column ve grid-auto-flow: dense.
• subgrid.
• @container sorguları.
• Otomatik ya da içsel sütun izleri (auto, min-content, max-content).

Bunlar ertelenmiş dilimlerdir, sessiz boşluklar değil. Bunlardan birine bağlı bir grid, blok akışına bozularak iner ve size bunu söyler.

Hata-durumunda-kapalı sınırı. Bir yakalama-karşı-motor genişlik uyumsuzluğu — ölçülen içerik genişliğinin, grid motorunun çözümlediği genişlikle uyuşmaması — yanlış yerleştirilmiş bir grid üretmek yerine hata durumunda kapalı kalır. Korunan kip ayrıca Safe CSS işleme kipiyle de uyumsuzdur: CssRenderingMode::Safe, CssLayoutMode::Retained ile birleştirildiğinde yapılandırma doğrulamasında IncompatibleRenderingModeException yükseltir. CssLayoutMode::Auto ayrılmıştır ve NotImplementedException yükseltir.

API yüzeyi

Simge	Konum	Rol
Config::withCssLayoutMode(CssLayoutMode $mode): self	src/Core/Config.php	Bir belgeyi Streaming (varsayılan) ya da Retained yerleşime dahil eder.
Config::withRetainedNodeBudget(int $budget): self	src/Core/Config.php	Korunan düğüm kümesini sınırlar ([5,000, 100,000], varsayılan 50,000).
Config::isRetainedMode(): bool	src/Core/Config.php	Belgenin korunan kipte olup olmadığını bildirir.
CssLayoutMode	src/Core/	Streaming, Retained; Auto ayrılmıştır (NotImplementedException).
GridLayoutEngine	src/Html/	Korunan grid yerleştirme motoru.
IncompatibleRenderingModeException	src/Exception/	Safe CSS kipi korunan kiple birleştirildiğinde fırlatılır.

Kod örneği — hızlı başlangıç

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

Kod örneği — üretim

Uyumsuz-kip durumunu yapılandırma sırasında saptayın ve etkin kipi geri okuyun; böylece yol açıktır.

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

Sınır durumları ve dikkat edilmesi gerekenler

• Streaming varsayılan kalır ve bayt düzeyinde özdeştir. Korunan kip çıktıyı yalnızca dahil ettiğiniz belge için değiştirir.
• Yalnızca belirli sütunlu grid-template-areas. Sütun otomatik akışı, yoğun paketleme, subgrid, @container ve içsel sütunlar HTML_GRID_REQUIRES_RETAINED uyarısını ve blok geri dönüşünü korur.
• Safe kipi karşılıklı olarak dışlayıcıdır. CssRenderingMode::Safe artı CssLayoutMode::Retained, IncompatibleRenderingModeException fırlatır.
• Auto ayrılmıştır. CssLayoutMode::Auto, NotImplementedException yükseltir; henüz kullanılabilir bir üçüncü seçenek değildir.
• Genişlik uyumsuzluğu hata durumunda kapalı kalır. Bir yakalama-karşı-motor içerik-genişliği uyuşmazlığı, yanlış işlenmek yerine reddedilir.

Performans

Korunan kip, tam bir belge ağacı yerine sınırlı bir düğüm kümesi tutar; retainedNodeBudget (varsayılan 50,000) bunu üst sınıra bağlar. Grid yerleştirme, düğüm ve hücre sayısında doğrusaldır. Sayfa başına performance_budget (wall_ms: 1500, peak_mb: 64) uygulanır; büyük grid’ler, düğüm bütçesini 100,000 tavanına doğru yükseltirken bütçeyi göz önünde bulundurmalıdır.

Güvenlik notları

Korunan kip giriş yüzeyini genişletmez. HTML güvenlik politikası, CSS özellik izin listesi ve ayrıştırıcı üst sınırları değişmeden uygulanır. Korunan düğüm bütçesi kendisi bir kaynak-tükenmesi sınırıdır: motorun tek bir belge için ne kadar yapı tutacağını üst sınıra bağlar.

Uygunluk

İfade	Standart	Madde
grid-template-areas grid hücrelerini adlandırır; adlandırılmış alanlar öğeleri yerleştirir.	W3C CSS Grid Layout Module Level 1	§7.3
Açık sabit, yüzde ve fr izleri içerik genişliğine göre boyutlanır.	W3C CSS Grid Layout Module Level 1	§7.2

Bu, belirli sütunlu bir grid-template-areas alt kümesinin önizleme uygulamasıdır. Özellik başına doğrulanmış durum CSS destek matrisinde izlenir; burada uçtan uca hiçbir uygunluk iddia edilmez. Hiçbir standart metin olduğu gibi aktarılmaz.

Ayrıca bakınız

• HTML işleme alt sistemi
• Tek geçişli akış kısıtları (ADR-001)
• Sayfalı medya CSS önizleme bayrakları
• Config modülü
• CSS destek matrisi