安定性: 実験的

CSS Grid（grid-template-areas）のための保持モードレイアウト

概要

オプトインのプレビュー。 保持モードはデフォルトでオフです。デフォルトの Streaming モードは、このモードが存在しなかったビルドとバイト単位で同一です。本物のグリッドを必要とするドキュメントに限ってオンにし、結果を検証してください。

デフォルトでは、レンダラーは単一パスかつストリーミングです（ADR-001 を参照）。grid-template-areas で宣言された CSS Grid は 1 回の前方パスでは配置できないため、ストリーミングエンジンは HTML_GRID_REQUIRES_RETAINED 警告を発行し、ブロックフローにフォールバックします。保持モードは、そのフォールバックを本物のレイアウトに置き換えるオプトインです。 Config::withCssLayoutMode(CssLayoutMode::Retained) は、確定列の grid-template-areas グリッドを GridLayoutEngine へ経路付けし、これが子要素を名前付きセルに配置します。

インストール

composer require nextpdf/core:^3

このレイアウトモードは core パッケージに同梱されています。Config::withCssLayoutMode のオプトインは @since 6.0.0 です。デフォルトは引き続き CssLayoutMode::Streaming です。

概念の概要

CssLayoutMode は Config 上の型付き列挙です。Streaming がデフォルトかつ従来からの挙動で、 Retained はドキュメントをグリッドエンジンにオプトインさせます。保持モードは有界の保持ノード集合（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）。

これらは延期されたスライスであり、暗黙のギャップではありません。これらのいずれかに依存するグリッドは、ブロックフローに劣化し、そのことを通知します。

フェイルクローズ境界。 キャプチャ対エンジンの幅の不一致 — 測定されたコンテンツ幅と、グリッドエンジンが解決に用いる幅が食い違う場合 — は、誤配置されたグリッドを生成するのではなくフェイルクローズします。保持モードは 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 を送出します。まだ使用可能な第 3 の選択肢ではありません。
幅の不一致はフェイルクローズします。 キャプチャ対エンジンのコンテンツ幅の食い違いは、誤ってレンダリングされるのではなく拒否されます。

パフォーマンス

保持モードは、完全なドキュメントツリーではなく有界のノード集合を保持します。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 サポートマトリクスで追跡されています。ここではエンドツーエンドの適合性は主張していません。規格本文の複製は行っていません。