Stabilität: Experimentell

Paged-Media-CSS-Preview-Flags (GCPM-Running-Content, benannte Seiten, Page Floats)

Auf einen Blick

Per Opt-in aktivierbare Vorschau. Diese vier CSS-Funktionen sind standardmäßig aus. Ist das Flag aus, erzeugt die Engine byte-identische Ausgabe zu einem Build, der die Funktion nie kannte. Schalten Sie eine Funktion nur ein, wenn Sie sie wollen, und validieren Sie das Ergebnis für Ihre Dokumente.

Der HTML-Renderer ergänzt vier per Opt-in aktivierbare Paged-Media-Funktionen aus den Modulen CSS Paged Media und Generated Content for Paged Media (GCPM). Jede ist ein eigenes Flag auf CssFeatureFlags. Jede trägt eine ehrliche Fail-closed-Grenze: Ein Konstrukt, das die Single-Pass-Engine nicht originalgetreu auflösen kann, wird verworfen oder mit einer benannten Diagnose degradiert — niemals falsch gerendert.

Funktion	Flag	Was sie bewirkt, wenn aktiviert
Named Strings (GCPM)	`runningStrings`	`string-set`-Erfassung plus `string()` in `@page`-Margin-Boxes — laufende Kopf- und Fußzeilen.
Benannte Seiten (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, die `page:`-Eigenschaft sowie `:first` / `:left` / `:right` / `:blank` — Margin-Boxes und Dekoration pro Seite.
Running Elements (GCPM)	`runningElements`	`position: running(<ident>)` plus `content: element(<ident>)` — wiederholt den Text eines Elements in einer Margin-Box.
Page Floats (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — verschiebt eine Box in das obere oder untere Band der Seite.

Installation

composer require nextpdf/core:^3

Die Flags werden im Core-Paket ausgeliefert. Die öffentliche Oberfläche von CssFeatureFlags ist @since 6.1.0. Die Engine-Version (Version::VERSION) bleibt unverändert; diese Funktionen sind additiv und standardmäßig aus.

Konzeptioneller Überblick

Der Renderer arbeitet single-pass und streamend (siehe ADR-001). Er hält keinen Dokumentbaum und schreibt die Ausgabe einmalig in Dokumentreihenfolge. Diese Einschränkung prägt jede Funktion hier. Jede Funktion löst auf, was sie in einem einzigen Vorwärtsdurchlauf sehen kann, und schlägt fail-closed bei allem fehl, was einen zweiten Durchlauf oder einen gehaltenen Baum erfordern würde. Die Grenze ist dokumentiert, nicht versteckt — zu wissen, wo eine Funktion endet, gehört zu ihrer Nutzung.

Sie aktivieren eine Funktion, indem Sie CssFeatureFlags mit auf true gesetztem Flag konstruieren und es an Config übergeben. Ist ein Flag aus, wird das entsprechende CSS geparst und ignoriert, genau wie eine nicht unterstützte Eigenschaft, sodass die Ausgabe byte-identisch zu einem Build ohne die Funktion ist.

Named Strings — `runningStrings`

string-set: <ident> content() erfasst einen Wert, während die Engine das Element passiert. Eine string(<ident>)-Referenz innerhalb einer @page-Margin-Box löst sich dann zum zuletzt auf dieser Seite gesehenen Wert auf. Dies ist der Standardmechanismus für eine laufende Kopfzeile, die das aktuelle Kapitel oder den aktuellen Abschnitt nachführt.

Die Auflösung erfolgt single-pass nach dem Prinzip „zuletzt auf dieser Seite gesehen”. Eine string()-Referenz löst sich zum letzten Wert auf, den die Engine erfasst hat, bevor sie die Margin-Boxes dieser Seite umbrochen hat.

Fail-closed-Grenze. Ist das Flag aus, löst sich string() zur leeren Zeichenkette auf und die Ausgabe bleibt byte-identisch. Eine fehlerhafte string-set-Content-Liste verwirft dieses eine Zuweisungspaar und fährt fort; sie bricht das Rendern nie ab.

Benannte Seiten — `namedPagesAdvanced`

Die Eigenschaft page: <ident> weist ein Element einem benannten Seitenkontext zu, und eine passende @page <ident>-Regel liefert die Margin-Boxes und die Seitendekoration dieses Kontexts. Die Seiten-Pseudoklassen :first, :left, :right und :blank wählen die erste Seite, Recto- und Verso-Seiten sowie absichtlich leere Seiten aus.

Diese Funktion wählt die Margin-Boxes und die Dekoration einer benannten oder Pseudo-Seite aus. Sie ändert nicht die Geometrie der Seite.

Fail-closed-Grenze. Eine benannte oder Pseudo-@page-Regel, die versucht, die Geometrie zu ändern — size, rotate oder ein Content-Box-Margin, der den Seitenbereich verändert —, schlägt fail-closed mit UnsupportedNamedPageException fehl, statt stillschweigend eine fehlausgerichtete Seite zu erzeugen. Der Pseudoklassen-Matching-Kanal ist die erste Teilmenge; breitere Selektorfälle sind zurückgestellt und dokumentiert.

Running Elements — `runningElements`

position: running(<ident>) entfernt ein Element aus dem normalen Fluss und parkt es unter einem Namen. content: element(<ident>) in einer Margin-Box wiederholt dieses Element dann auf jeder Seite. Verwenden Sie es, wenn eine Kopfzeile den vollständig gestylten Text einer Überschrift benötigt, nicht nur eine erfasste Zeichenkette.

Fail-closed-Grenze. Diese Teilmenge wiederholt nur den Text des Running Elements. Reicher Inhalt — Bilder, ersetzte Elemente, verschachtelte Blockstruktur — wird verworfen, und die Engine gibt eine HTML_RUNNING_ELEMENT_DEGRADED-Diagnose aus, sodass der Verlust sichtbar ist, nicht stillschweigend. Ein running()-Element, das sich selbst referenziert, ein verschachteltes running() oder eine Erfassung, die das interne Budget überschreitet, schlägt fail-closed fehl. Ist das Flag aus, sind running() und element() inert.

Page Floats — `pageFloats`

float: top, float: bottom und float: snap verschieben eine Box in das obere oder untere Band der Seite entlang der Block-Achse und reservieren die Höhe des Bandes, sodass der umgebende Text um die reservierte Region herum neu umbrochen wird.

float: bottom (sowie snap, das sich zum unteren Band auflöst) ist der Fall, den die Single-Pass-Engine direkt verarbeitet: Die Box wird erfasst und beim Schließen der Seite in deren unterem Band platziert. float: top degeneriert zum oberen Band der Seite.

Fail-closed-Grenze. snap in der Inline-Achse (snap-inline) wird nicht unterstützt. Eine Box, die einen unverschiebbaren Nebeneffekt trägt — zum Beispiel eine Link-Annotation, deren Rechteck an ihre Flussposition gebunden ist —, kann nicht sicher verschoben werden und fällt daher auf den normalen Fluss zurück; die Engine gibt dabei eine HTML_PAGE_FLOAT_*-Diagnose aus, die den Rückfall erklärt. Ist das Flag aus, wird float: top | bottom | snap als nicht unterstützter Wert behandelt und ignoriert.

API-Oberfläche

Symbol	Ort	Rolle
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	Unveränderliches Opt-in-Flag-Set; der Konstruktor nimmt `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` (alle standardmäßig `false`).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Hängt das Flag-Set an eine Dokumentkonfiguration an.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	Löst ein Flag-Set für einen Rendering-Modus auf (Safe-Modus erzwingt jedes Flag aus; Normal-Modus nutzt das explizite Set oder `allEnabled()`, wenn keines angegeben ist).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	Wird geworfen, wenn eine benannte/Pseudo-`@page`-Regel die Seitengeometrie ändert.

Diagnostische Warncodes treten über den Advisory-Kanal des Render-Ergebnisses zutage: HTML_RUNNING_ELEMENT_DEGRADED, die HTML_RUNNING_ELEMENT_*-Familie und die HTML_PAGE_FLOAT_*-Familie.

Codebeispiel — Schnellstart

Aktivieren Sie Named Strings für eine laufende Kopfzeile, die das aktuelle Kapitel nachführt.

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

Codebeispiel — Produktion

Aktivieren Sie mehrere Flags gemeinsam und behandeln Sie den Advisory-Kanal als Signal dafür, dass ein Konstrukt degradiert wurde. Die Flags sind unabhängig; aktivieren Sie nur die, die Sie nutzen.

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

Randfälle & Fallstricke

Alle vier Flags sind unabhängig und standardmäßig aus. Ein ausgeschaltetes Flag liefert byte-identische Ausgabe. Aktivieren Sie nur, was Sie nutzen.
string() ist leer, wenn runningStrings aus ist, von Entwurf wegen. Für den Aus-Fall gibt es keine Warnung; das ist der dokumentierte Standard.
Running Elements wiederholen nur Text. Bilder und verschachtelte Blöcke innerhalb eines Running Elements werden mit HTML_RUNNING_ELEMENT_DEGRADED verworfen. Prüfen Sie den Advisory-Kanal.
Benannte Seiten können die Geometrie nicht ändern. Eine geometrieändernde benannte/Pseudo-@page-Regel wirft UnsupportedNamedPageException. Legen Sie Seitengröße und -rotation über Config fest, nicht über eine benannte @page-Regel.
Page Floats halten Links im Fluss. Eine geflotete Box, die eine Link-Annotation enthält, fällt mit einer HTML_PAGE_FLOAT_*-Diagnose auf den normalen Fluss zurück, weil das Link-Rechteck an seine Flussposition gebunden ist.

Performance

Jede Funktion fügt eine begrenzte Menge Single-Pass-Arbeit hinzu: Named Strings erfassen einen Wert pro string-set-Element; benannte Seiten fügen eine Margin-Box-Auflösung pro Seite hinzu; Running Elements erfassen einen Textpuffer pro geparktem Element; Page Floats reservieren ein Band pro Seite. Keine hält einen Dokumentbaum, sodass das O(Verschachtelungstiefe)-Speichermodell des streamenden Renderers erhalten bleibt. Das performance_budget pro Seite (wall_ms: 1500, peak_mb: 64) bleibt unverändert.

Sicherheitshinweise

Diese Flags weiten die Eingabeoberfläche nicht aus. Die HTML-Sicherheitsrichtlinie, die Allowlist der CSS-Eigenschaften sowie die Stylesheet-Byte- und Verschachtelungslimits gelten unverändert. Erfasster String- und Element-Inhalt wird über denselben Ausgabepfad escaped wie jeder andere Text. Die Funktionen fügen Layoutverhalten hinzu, keinen neuen Ingestion-Kanal.

Konformität

Aussage	Standard	Klausel
`string-set` erfasst eine benannte Zeichenkette; `string()` löst sie in einer Seiten-Margin-Box auf.	W3C CSS Generated Content for Paged Media	§3
`position: running()` entfernt ein Element aus dem Fluss; `content: element()` wiederholt es.	W3C CSS Generated Content for Paged Media	§5
Die `page`-Eigenschaft und `@page <ident>` wählen einen benannten Seitenkontext aus.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` flotet eine Box in der Block-Achse zu einem Seitenband.	W3C CSS Page Floats Level 3	§5

Dies sind Vorschau-Implementierungen von Funktionen aus Arbeitsgruppen-Modulen. NextPDF implementiert eine Single-Pass-Teilmenge mit den oben dokumentierten Fail-closed-Grenzen. Der pro-Eigenschaft verifizierte Status wird in der CSS-Support-Matrix nachgehalten; hier wird keine Ende-zu-Ende-Konformität beansprucht. Es wird kein Standardtext wiedergegeben.