stabilitas: Eksperimental

Tata letak mode-dipertahankan untuk CSS Grid (grid-template-areas)

Sekilas

Preview opt-in. Mode dipertahankan default-mati. Mode Streaming default bersifat byte-identik dengan build yang tidak pernah mengenal mode ini. Aktifkan hanya untuk dokumen yang membutuhkan grid sungguhan, dan validasi hasilnya.

Secara default, perender bersifat satu-lintasan dan streaming (lihat ADR-001). Sebuah CSS Grid yang dideklarasikan dengan grid-template-areas tidak dapat ditempatkan dalam satu lintasan maju, sehingga mesin streaming memancarkan peringatan HTML_GRID_REQUIRES_RETAINED dan kembali ke aliran blok. Mode dipertahankan adalah opt-in yang menggantikan fallback itu dengan tata letak sungguhan: Config::withCssLayoutMode(CssLayoutMode::Retained) merutekan grid grid-template-areas berkolom-pasti melalui GridLayoutEngine, yang menempatkan anak-anaknya ke dalam sel bernamanya.

Pemasangan

composer require nextpdf/core:^3

Mode tata letak ini disertakan dalam paket core. Opt-in Config::withCssLayoutMode adalah @since 6.0.0. Default tetap CssLayoutMode::Streaming.

Ikhtisar konseptual

CssLayoutMode adalah enum bertipe pada Config. Streaming adalah default dan perilaku historisnya; Retained memilihkan sebuah dokumen ke mesin grid. Mode dipertahankan menyimpan kumpulan node dipertahankan yang terbatas (retainedNodeBudget, default 50,000, dijepit ke [5,000, 100,000]) sehingga mesin dapat menyelesaikan grid yang tak bisa diselesaikan streaming — tanpa meninggalkan disiplin memori mesin.

Saat mode dipertahankan aktif dan mesin menemui grid grid-template-areas yang kolomnya pasti, ia menata grid itu secara sungguhan. Kolom pasti adalah panjang tetap, persentase, atau unit fr yang teratasi terhadap lebar konten. Baris mengalir secara otomatis. Anak-anak ditetapkan ke sel yang dipilih oleh nama area-nya.

ADR-001 mencatat invarian streaming. Amandemen 2026-06-28 terhadap ADR-001 menambahkan pengecualian opt-in untuk mode dipertahankan: default streaming tidak tersentuh dan tetap menjadi model satu-lintasan; mode dipertahankan adalah pengecualian opt-in yang terbatas secara eksplisit untuk kasus grid.

Batas — apa yang ditata mode dipertahankan, dan apa yang tetap kembali ke fallback

Mode dipertahankan menangani kasus grid-template-areas berkolom-pasti dan hanya kasus itu. Segala sesuatu di luarnya tetap memakai peringatan HTML_GRID_REQUIRES_RETAINED dan fallback blok, bahkan dengan mode dipertahankan aktif:

grid-auto-flow: column dan grid-auto-flow: dense.
subgrid.
Kueri @container.
Trek kolom otomatis atau intrinsik (auto, min-content, max-content).

Ini adalah irisan yang ditangguhkan, bukan kesenjangan diam. Sebuah grid yang bergantung pada salah satunya akan terdegradasi ke aliran blok dan memberitahukan Anda.

Batasan fail-closed. Ketidaksesuaian lebar tangkapan-versus-mesin — lebar konten terukur tidak setuju dengan lebar yang dipakai mesin grid sebagai acuan — gagal secara fail-closed alih-alih menghasilkan grid yang salah tempat. Mode dipertahankan juga tidak kompatibel dengan mode rendering Safe CSS: CssRenderingMode::Safe yang digabung dengan CssLayoutMode::Retained memunculkan IncompatibleRenderingModeException saat validasi config. CssLayoutMode::Auto dicadangkan dan memunculkan NotImplementedException.

Permukaan API

Simbol	Lokasi	Peran
`Config::withCssLayoutMode(CssLayoutMode $mode): self`	`src/Core/Config.php`	Memilihkan sebuah dokumen ke tata letak `Streaming` (default) atau `Retained`.
`Config::withRetainedNodeBudget(int $budget): self`	`src/Core/Config.php`	Membatasi kumpulan node dipertahankan (`[5,000, 100,000]`, default `50,000`).
`Config::isRetainedMode(): bool`	`src/Core/Config.php`	Melaporkan apakah dokumen berada dalam mode dipertahankan.
`CssLayoutMode`	`src/Core/`	`Streaming`, `Retained`; `Auto` dicadangkan (`NotImplementedException`).
`GridLayoutEngine`	`src/Html/`	Mesin penempatan grid mode-dipertahankan.
`IncompatibleRenderingModeException`	`src/Exception/`	Dilempar saat mode Safe CSS digabung dengan mode dipertahankan.

Contoh kode — Mulai cepat

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

Contoh kode — Produksi

Deteksi kasus mode-tak-kompatibel pada saat konfigurasi, dan baca kembali mode aktif agar jalurnya eksplisit.

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

Kasus tepi & jebakan

Streaming tetap default dan byte-identik. Mode dipertahankan mengubah keluaran hanya untuk dokumen yang Anda opt-in.
Hanya grid-template-areas berkolom-pasti. Auto-flow kolom, dense packing, subgrid, @container, dan kolom intrinsik tetap memakai peringatan HTML_GRID_REQUIRES_RETAINED dan fallback blok.
Mode Safe saling eksklusif. CssRenderingMode::Safe plus CssLayoutMode::Retained melempar IncompatibleRenderingModeException.
Auto dicadangkan. CssLayoutMode::Auto memunculkan NotImplementedException; ia belum menjadi opsi ketiga yang dapat dipakai.
Ketidaksesuaian lebar gagal secara fail-closed. Ketidaksetujuan lebar konten tangkapan-versus-mesin ditolak, bukan dirender keliru.

Kinerja

Mode dipertahankan menyimpan kumpulan node yang terbatas alih-alih pohon dokumen penuh; retainedNodeBudget (default 50,000) membatasinya. Penempatan grid bersifat linear terhadap jumlah node dan sel. performance_budget per-halaman (wall_ms: 1500, peak_mb: 64) berlaku; grid besar sebaiknya mempertimbangkan anggaran itu saat menaikkan anggaran node menuju langit-langit 100,000-nya.

Catatan keamanan

Mode dipertahankan tidak memperlebar permukaan masukan. Kebijakan keamanan HTML, allowlist properti CSS, dan cap parser berlaku tanpa perubahan. Anggaran node dipertahankan itu sendiri merupakan batas pemulihan-sumber-daya: ia membatasi seberapa banyak struktur yang akan disimpan mesin untuk satu dokumen.

Konformitas

Pernyataan	Standar	Klausul
`grid-template-areas` menamai sel grid; area bernama menempatkan item.	W3C CSS Grid Layout Module Level 1	§7.3
Trek tetap, persentase, dan `fr` eksplisit diukur terhadap lebar konten.	W3C CSS Grid Layout Module Level 1	§7.2

Ini adalah implementasi preview dari subset grid-template-areas berkolom-pasti. Status terverifikasi per-properti dilacak dalam matriks dukungan CSS; tidak ada konformitas ujung-ke-ujung yang diklaim di sini. Tidak ada teks standar yang direproduksi.