穩定性: 實驗性

CSS Grid 的保留模式配置（grid-template-areas）

概覽

可選擇啟用的預覽。 保留模式預設為關閉。預設的 Streaming 模式與一個從未認識此模式的建置版本位元組完全相同。只為那些需要真正格線的文件將它開啟，並驗證結果。

預設情況下，算繪器是單遍且串流式的（請參閱 ADR-001）。一個以 grid-template-areas 宣告的 CSS Grid 無法在一次前向遍歷中放置，因此串流引擎會發出一個 HTML_GRID_REQUIRES_RETAINED 警告並退回區塊流動。保留模式是用來以真正的配置取代該退回的選擇性啟用：Config::withCssLayoutMode(CssLayoutMode::Retained) 會將一個定行的 grid-template-areas 格線路由穿過 GridLayoutEngine，由它將子元素放入其具名的儲存格中。

安裝

composer require nextpdf/core:^3

此配置模式隨核心套件一起出貨。Config::withCssLayoutMode 這項選擇性啟用為 @since 6.0.0。預設值維持為 CssLayoutMode::Streaming。

概念總覽

CssLayoutMode 是 Config 上的一個具型別列舉。Streaming 是預設值，也是歷史以來的行為；Retained 則讓一份文件選擇進入 grid 引擎。保留模式持有一個有界的保留節點集合（即 retainedNodeBudget，預設為 50,000，會被限制在 [5,000, 100,000]），讓引擎能夠解析串流所無法解析的格線——而不放棄引擎的記憶體紀律。

當保留模式開啟、且引擎遇到一個各行皆為定值的 grid-template-areas 格線時，它會真正地配置該格線。定行是固定長度、百分比，或相對於內容寬度解析的 fr 單位。各列會自動流動。子元素會被指派到其區域名稱所選取的儲存格。

ADR-001 記載了串流不變量。對 ADR-001 的 2026-06-28 修訂加入了一個保留模式選擇性啟用的特例切割：串流預設不受影響，並維持為單遍模型；保留模式是針對格線情況、一個明確有界的選擇性啟用例外。

邊界——保留模式會配置什麼，以及什麼仍會退回

保留模式只處理定行的 grid-template-areas 情況，且僅此一種。其外的一切都會保留 HTML_GRID_REQUIRES_RETAINED 警告與區塊退回，即使保留模式已開啟：

grid-auto-flow: column 與 grid-auto-flow: dense。
subgrid。
@container 查詢。
自動或內在的行軌（auto、min-content、max-content）。

這些是延後處理的切片，而非默默存在的缺口。一個依賴其中任一者的格線會降級為區塊流動，並會如此告知你。

Fail-closed 邊界。 一個擷取與引擎之間的寬度不一致——量測到的內容寬度與 grid 引擎所解析依據的寬度有出入——會 fail closed，而不是產生一個放錯位置的格線。保留模式也與 Safe CSS 算繪模式不相容：CssRenderingMode::Safe 與 CssLayoutMode::Retained 結合時，會在設定驗證時引發 IncompatibleRenderingModeException。CssLayoutMode::Auto 為保留用途，會引發 NotImplementedException。

API 介面

符號	位置	角色
`Config::withCssLayoutMode(CssLayoutMode $mode): self`	`src/Core/Config.php`	讓一份文件選擇進入 `Streaming`（預設）或 `Retained` 配置。
`Config::withRetainedNodeBudget(int $budget): self`	`src/Core/Config.php`	限制保留節點集合（`[5,000, 100,000]`，預設 `50,000`）。
`Config::isRetainedMode(): bool`	`src/Core/Config.php`	回報該文件是否處於保留模式。
`CssLayoutMode`	`src/Core/`	`Streaming`、`Retained`；`Auto` 為保留用途（`NotImplementedException`）。
`GridLayoutEngine`	`src/Html/`	保留模式的格線放置引擎。
`IncompatibleRenderingModeException`	`src/Exception/`	當 Safe CSS 模式與保留模式結合時拋出。

程式碼範例——快速開始

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

程式碼範例——正式環境

在設定時偵測不相容模式的情況，並讀回作用中的模式，使路徑明確。

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

邊界情況與陷阱

Streaming 仍是預設且位元組完全相同。 保留模式只會改變你選擇啟用的那份文件的輸出。
僅限定行的 grid-template-areas。 行自動流動、密集封裝、subgrid、@container 與內在行都會保留 HTML_GRID_REQUIRES_RETAINED 警告與區塊退回。
Safe 模式互斥。 CssRenderingMode::Safe 加上 CssLayoutMode::Retained 會拋出 IncompatibleRenderingModeException。
Auto 為保留用途。 CssLayoutMode::Auto 會引發 NotImplementedException；它尚未成為一個可用的第三選項。
寬度不一致會 fail closed。 一個擷取與引擎之間的內容寬度出入會被拒絕，而不是錯誤地算繪。

效能

保留模式持有一個有界的節點集合，而非完整的文件樹；retainedNodeBudget（預設 50,000）為它設限。格線放置的時間複雜度與節點及儲存格數量呈線性。逐頁的 performance_budget（wall_ms: 1500、peak_mb: 64）適用；大型格線在將節點預算往其 100,000 上限調高時，應將預算謹記在心。

安全性注意事項

保留模式不會擴大輸入面。HTML 安全性政策、CSS 屬性允許清單，以及解析器上限均維持不變地適用。保留節點預算本身就是一個資源耗盡的界限：它為引擎針對單一文件所持有的結構量設限。

一致性

陳述	規範	條款
`grid-template-areas` 為格線儲存格命名；具名區域放置項目。	W3C CSS Grid Layout Module Level 1	§7.3
明確的固定、百分比與 `fr` 軌會相對於內容寬度調整大小。	W3C CSS Grid Layout Module Level 1	§7.2

這是一個定行 grid-template-areas 子集的預覽實作。逐屬性的已驗證狀態追蹤於 CSS 支援矩陣；此處不主張任何端到端一致性。未重現任何規範文字。