ページ付きメディア CSS プレビューフラグ（GCPM ランニングコンテンツ、名前付きページ、ページフロート）

概要

オプトインのプレビュー。 これら 4 つの CSS 機能はデフォルトでオフです。フラグがオフのとき、エンジンはその機能が存在しなかったビルドとバイト単位で同一の出力を生成します。必要なときにのみ機能をオンにし、ご自身のドキュメントで結果を検証してください。

HTML レンダラーは、CSS Paged Media モジュールと Generated Content for Paged Media （GCPM）モジュールから、オプトイン式のページ付きメディア機能を 4 つ追加します。それぞれが CssFeatureFlags 上の独立したフラグです。それぞれが正直なフェイルクローズ境界を備えています。単一パスのエンジンが忠実に解決できない構成は、名前付き診断とともに破棄または劣化させられ、決して誤ってレンダリングされることはありません。

機能	フラグ	オンのときの動作
名前付き文字列（GCPM）	runningStrings	string-set によるキャプチャと、@page マージンボックス内の string() — ランニングヘッダーとフッター。
名前付きページ（Paged Media L3）	namedPagesAdvanced	@page <ident>、page: プロパティ、:first / :left / :right / :blank — ページごとのマージンボックスと装飾。
ランニング要素（GCPM）	runningElements	position: running(<ident>) と content: element(<ident>) — 要素のテキストをマージンボックスに再生。
ページフロート（Page Floats L3）	pageFloats	float: top | bottom | snap — ボックスをページの上部または下部のバンドへ移動。

インストール

composer require nextpdf/core:^3

これらのフラグは core パッケージに同梱されています。CssFeatureFlags のパブリックサーフェスは @since 6.1.0 です。エンジンのバージョン（Version::VERSION）は変更されません。これらの機能は追加的で、デフォルトでオフです。

概念の概要

レンダラーは単一パスかつストリーミングです（ADR-001 を参照）。ドキュメントツリーを保持せず、ドキュメント順に一度だけ出力を書き出します。その制約がここでのすべての機能を形作っています。各機能は、1 回の前方パスで見えるものを解決し、2 回目のパスや保持されたツリーを必要とするものについてはフェイルクローズします。境界は隠されるのではなく文書化されています。機能がどこで止まるのかを知ることは、その機能を使ううえでの一部です。

機能を有効にするには、フラグを true にして CssFeatureFlags を構築し、それを Config に渡します。フラグがオフのとき、対応する CSS はサポートされていないプロパティとまったく同じようにパースされて無視されるため、出力はその機能を持たないビルドとバイト単位で同一になります。

名前付き文字列 — runningStrings

string-set: <ident> content() は、エンジンが要素を通過する際に値を記録します。@page マージンボックス内の string(<ident>) 参照は、そのページで直近に見られた値に解決されます。 これは、現在の章やセクションを追跡するランニングヘッダーの標準的なメカニズムです。

解決は単一パスの「このページで最後に見たもの」です。string() 参照は、エンジンがそのページのマージンボックスをレイアウトする前に記録した最後の値に解決されます。

フェイルクローズ境界。 フラグがオフのとき、string() は空文字列に解決され、出力はバイト単位で同一のままになります。不正な形式の string-set コンテンツリストは、その 1 つの代入ペアを破棄して継続します。レンダリングを中断することは決してありません。

名前付きページ — namedPagesAdvanced

page: <ident> プロパティは要素を名前付きページコンテキストに割り当て、対応する @page <ident> ルールがそのコンテキストのマージンボックスとページ装飾を提供します。ページ擬似クラス :first、:left、:right、:blank は、最初のページ、表（レクト）と裏（ベルソ） のページ、意図的な空白ページを選択します。

この機能は、名前付きページまたは擬似ページのマージンボックスと装飾を選択します。ページのジオメトリは変更しません。

フェイルクローズ境界。 ジオメトリ — size、rotate、またはページ領域をリサイズするコンテンツボックスのマージン — を変更しようとする名前付きまたは擬似的な @page ルールは、 ずれたページを暗黙のうちに生成するのではなく、UnsupportedNamedPageException でフェイルクローズします。擬似クラスのマッチングチャンネルが最初のスライスです。より広いセレクターケースは延期され、文書化されています。

ランニング要素 — runningElements

position: running(<ident>) は要素を通常のフローから取り除き、名前のもとに退避させます。 マージンボックス内の content: element(<ident>) は、その要素を各ページで再生します。見出しの完全なスタイル付きテキストが必要で、単にキャプチャした文字列だけでは足りないヘッダーに使います。

フェイルクローズ境界。 このスライスはランニング要素のテキストのみを再生します。リッチコンテンツ — 画像、置換要素、入れ子のブロック構造 — は破棄され、エンジンは HTML_RUNNING_ELEMENT_DEGRADED 診断を発行するため、損失は暗黙ではなく可視になります。自身を参照する running() 要素、入れ子の running()、または内部予算を超えるキャプチャはフェイルクローズします。フラグがオフのとき、running() と element() は不活性です。

ページフロート — pageFloats

float: top、float: bottom、float: snap は、ブロック軸方向でボックスをページの上部または下部のバンドへ移動させ、そのバンドの高さを確保するため、周囲のテキストは確保された領域の周りで再フローします。

float: bottom（および下部バンドに解決される snap）は、単一パスのエンジンが直接処理するケースです。ボックスはキャプチャされ、ページが閉じる際にページの下部バンドに配置されます。 float: top はページ上部のバンドに退化します。

フェイルクローズ境界。 インライン軸での snap（snap-inline）はサポートされていません。 移動できない副作用を伴うボックス — たとえば、矩形がフロー位置に束縛されているリンク注釈 — は安全に再配置できないため、通常のフローにフォールバックし、エンジンはそのフォールバックを説明する HTML_PAGE_FLOAT_* 診断を発行します。フラグがオフのとき、float: top | bottom | snap はサポートされていない値として扱われ、無視されます。

API サーフェス

シンボル	場所	役割
CssFeatureFlags	src/Html/CssFeatureFlags.php	イミュータブルなオプトインフラグ集合。コンストラクターは runningStrings、namedPagesAdvanced、runningElements、pageFloats を取る（すべてデフォルト false）。
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	フラグ集合をドキュメント設定にアタッチする。
CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self	src/Html/CssFeatureFlags.php	レンダリングモードに対するフラグ集合を解決する（Safe モードはすべてのフラグを強制的にオフにし、Normal モードは明示的な集合を使用し、いずれも指定されない場合は allEnabled() を使用）。
UnsupportedNamedPageException	src/Html/PagedMedia/UnsupportedNamedPageException.php	名前付き/擬似的な @page ルールがページジオメトリを変更したときにスローされる。

診断警告コードはレンダー結果のアドバイザリチャンネルを通じて表面化します。すなわち HTML_RUNNING_ELEMENT_DEGRADED、HTML_RUNNING_ELEMENT_* ファミリー、HTML_PAGE_FLOAT_* ファミリーです。

コードサンプル — クイックスタート

現在の章を追跡するランニングヘッダーのために、名前付き文字列を有効にします。

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(runningStrings: true),
);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<style>'
    . 'h2 { string-set: chapter content(); }'
    . '@page { @top-center { content: string(chapter); } }'
    . '</style>'
    . '<h2>Introduction</h2><p>Body text…</p>',
);
$doc->save(__DIR__ . '/running-header.pdf');

コードサンプル — 本番

複数のフラグをまとめて有効にし、アドバイザリチャンネルを、構成が劣化したというシグナルとして扱います。これらのフラグは独立しています。使うものだけをオンにしてください。

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Exception\UnsupportedNamedPageException;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(new CssFeatureFlags(
    runningStrings: true,
    namedPagesAdvanced: true,
    runningElements: true,
    pageFloats: true,
));

$doc = Document::createStandalone($config);
$doc->addPage();

try {
    $doc->writeHtml($html);
} catch (UnsupportedNamedPageException $e) {
    // A named @page rule tried to change page geometry (size/rotate/margin).
    // The engine fails closed rather than emit a misaligned page.
    throw $e;
}

$doc->save($out);

// Inspect $doc's advisory channel for HTML_RUNNING_ELEMENT_DEGRADED and
// HTML_PAGE_FLOAT_* before treating the output as final.

エッジケースと落とし穴

• 4 つのフラグはすべて独立しており、デフォルトでオフです。 オフのフラグはバイト単位で同一の出力を生成します。使うものだけを有効にしてください。
• runningStrings がオフのとき string() は空になります。これは設計どおりです。オフのケースに対する警告はありません。それが文書化されたデフォルトです。
• ランニング要素はテキストのみを再生します。 ランニング要素内の画像や入れ子のブロックは HTML_RUNNING_ELEMENT_DEGRADED とともに破棄されます。アドバイザリチャンネルを確認してください。
• 名前付きページはジオメトリを変更できません。 ジオメトリを変更する名前付き/擬似的な @page ルールは UnsupportedNamedPageException をスローします。ページサイズと回転は名前付き @page ルールではなく Config を通じて設定してください。
• ページフロートはリンクをフローに残します。 リンク注釈を含むフロートされたボックスは、 リンクの矩形がフロー位置に束縛されているため、HTML_PAGE_FLOAT_* 診断とともに通常のフローにフォールバックします。

パフォーマンス

各機能は、有界量の単一パス作業を追加します。名前付き文字列は string-set 要素ごとに 1 つの値を記録し、名前付きページはページごとのマージンボックス解決を追加し、ランニング要素は退避された要素ごとに 1 つのテキストバッファをキャプチャし、ページフロートはページごとに 1 つのバンドを確保します。いずれもドキュメントツリーを保持しないため、ストリーミングレンダラーの O(ネスト深さ) のメモリモデルが維持されます。ページごとの performance_budget（wall_ms: 1500、peak_mb: 64）は変更されません。

セキュリティに関する注意

これらのフラグは入力サーフェスを拡大しません。HTML セキュリティポリシー、CSS プロパティの許可リスト、スタイルシートのバイト数とネストの上限は変更されずに適用されます。キャプチャされた文字列および要素のコンテンツは、他のテキストと同じ出力パスを通じてエスケープされます。これらの機能はレイアウトの挙動を追加するものであり、新たな取り込みチャンネルではありません。

適合性

記述	仕様	条項
string-set は名前付き文字列を記録し、string() はそれをページのマージンボックスで解決する。	W3C CSS Generated Content for Paged Media	§3
position: running() は要素をフローから取り除き、content: element() はそれを再生する。	W3C CSS Generated Content for Paged Media	§5
page プロパティと @page <ident> は名前付きページコンテキストを選択する。	W3C CSS Paged Media Module Level 3	§3
float: top | bottom | snap はブロック軸方向でボックスをページバンドへフロートさせる。	W3C CSS Page Floats Level 3	§5

これらはワーキンググループのモジュール機能のプレビュー実装です。NextPDF は、上記の文書化されたフェイルクローズ境界を伴う単一パスのサブセットを実装しています。プロパティごとの検証済みステータスは CSS サポートマトリクス で追跡されています。ここではエンドツーエンドの適合性は主張していません。規格本文の複製は行っていません。

関連項目

• HTML レンダリングサブシステム
• 単一パスストリーミングの制約（ADR-001）
• 保持モードレイアウト（grid-template-areas）
• Config モジュール
• CSS サポートマトリクス