stabiliteit: Experimenteel

Paged-media CSS-previewvlaggen (GCPM running content, named pages, page floats)

In een oogopslag

Opt-in preview. Deze vier CSS-functies staan standaard uit. Wanneer de vlag uit staat, produceert de engine byte-identieke uitvoer ten opzichte van een build die de functie nooit heeft gekend. Zet een functie alleen aan wanneer je die wilt, en valideer het resultaat voor je documenten.

De HTML-renderer voegt vier opt-in paged-mediafuncties toe uit de CSS Paged Media- en Generated Content for Paged Media (GCPM)-modules. Elk is een aparte vlag op CssFeatureFlags. Elk draagt een eerlijke fail-closed-grens: een constructie die de single-pass-engine niet getrouw kan oplossen, wordt verwijderd of gedegradeerd met een benoemde diagnostiek, nooit verkeerd weergegeven.

Functie	Vlag	Wat het doet wanneer aan
Named strings (GCPM)	`runningStrings`	`string-set`-vastlegging plus `string()` in `@page`-margevakken — running headers en footers.
Named pages (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, de `page:`-eigenschap en `:first` / `:left` / `:right` / `:blank` — margevakken en decoratie per pagina.
Running elements (GCPM)	`runningElements`	`position: running(<ident>)` plus `content: element(<ident>)` — speelt de tekst van een element opnieuw af in een margevak.
Page floats (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — verplaatst een vak naar de boven- of onderband van de pagina.

Installeren

composer require nextpdf/core:^3

De vlaggen worden meegeleverd in het core-pakket. Het publieke oppervlak van CssFeatureFlags is @since 6.1.0. De engineversie (Version::VERSION) is onveranderd; deze functies zijn additief en standaard uit.

Conceptueel overzicht

De renderer is single-pass en streaming (zie ADR-001). Hij houdt geen documentboom bij en schrijft de uitvoer eenmaal in documentvolgorde. Die beperking vormt elke functie hier. Elke functie lost op wat hij in één voorwaartse pass kan zien en faalt gesloten op alles wat een tweede pass of een behouden boom zou vereisen. De grens is gedocumenteerd, niet verborgen — weten waar een functie stopt is onderdeel van het gebruik ervan.

Je schakelt een functie in door CssFeatureFlags te construeren met de vlag op true en die door te geven aan Config. Wanneer een vlag uit staat, wordt de bijbehorende CSS geparseerd en genegeerd, precies zoals een niet-ondersteunde eigenschap zou worden, zodat de uitvoer byte-identiek is aan een build zonder de functie.

Benoemde strings — `runningStrings`

string-set: <ident> content() legt een waarde vast terwijl de engine het element passeert. Een string(<ident>)-verwijzing binnen een @page-margevak lost dan op naar de meest recente waarde die op die pagina is gezien. Dit is het standaardmechanisme voor een running header die het huidige hoofdstuk of de huidige sectie volgt.

De oplossing is single-pass “laatst gezien op deze pagina”. Een string()-verwijzing lost op naar de laatste waarde die de engine vastlegde voordat hij de margevakken van die pagina opmaakte.

Fail-closed-grens. Met de vlag uit lost string() op naar de lege string en blijft de uitvoer byte-identiek. Een misvormde string-set-contentlijst laat dat ene toewijzingspaar vallen en gaat door; het breekt de render nooit af.

Benoemde pagina’s — `namedPagesAdvanced`

De page: <ident>-eigenschap wijst een element toe aan een named page-context, en een bijpassende @page <ident>-regel levert de margevakken en paginadecoratie van die context. De paginapseudoklassen :first, :left, :right en :blank selecteren de eerste pagina, recto- en versopagina’s en opzettelijk blanco pagina’s.

Deze functie selecteert de margevakken en decoratie van een named of pseudo page. Hij verandert de pagina-geometrie niet.

Fail-closed-grens. Een named of pseudo @page-regel die de geometrie probeert te veranderen — size, rotate of een content-boxmarge die het paginavlak herschaalt — faalt gesloten met UnsupportedNamedPageException in plaats van stilletjes een verkeerd uitgelijnde pagina te produceren. Het matchkanaal voor pseudoklassen is het eerste deel; bredere selectorgevallen zijn uitgesteld en gedocumenteerd.

Lopende elementen — `runningElements`

position: running(<ident>) haalt een element uit de normale flow en parkeert het onder een naam. content: element(<ident>) in een margevak speelt dat element dan op elke pagina opnieuw af. Gebruik het wanneer een header de volledige opgemaakte tekst van een kop nodig heeft, niet slechts een vastgelegde string.

Fail-closed-grens. Dit deel speelt alleen de tekst van het running element opnieuw af. Rijke content — afbeeldingen, vervangen elementen, geneste blokstructuur — wordt verwijderd, en de engine geeft een HTML_RUNNING_ELEMENT_DEGRADED-diagnostiek af zodat het verlies zichtbaar is, niet stil. Een running()-element dat naar zichzelf verwijst, een geneste running() of een vastlegging die het interne budget overschrijdt, faalt gesloten. Met de vlag uit zijn running() en element() inert.

Pagina-floats — `pageFloats`

float: top, float: bottom en float: snap verplaatsen een vak naar de boven- of onderband van de pagina in de blokas, waarbij de hoogte van de band wordt gereserveerd zodat de omringende tekst rond het gereserveerde gebied opnieuw stroomt.

float: bottom (en snap die naar de onderband oplost) is het geval dat de single-pass-engine direct afhandelt: het vak wordt vastgelegd en in de onderband van de pagina geplaatst terwijl de pagina sluit. float: top degenereert naar de band aan de paginabovenkant.

Fail-closed-grens. snap in de inline-as (snap-inline) wordt niet ondersteund. Een vak dat een onverplaatsbaar neveneffect draagt — bijvoorbeeld een linkannotatie, waarvan de rechthoek gebonden is aan zijn flowpositie — kan niet veilig worden verplaatst, dus valt het terug op normale flow en geeft de engine een HTML_PAGE_FLOAT_*-diagnostiek af die de terugval uitlegt. Met de vlag uit wordt float: top | bottom | snap behandeld als een niet-ondersteunde waarde en genegeerd.

API-oppervlak

Symbool	Locatie	Rol
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	Onveranderlijke opt-in-vlaggenset; de constructor neemt `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` (alle standaard `false`).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Koppelt de vlaggenset aan een documentconfiguratie.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	Lost een vlaggenset op voor een renderingmodus (Safe mode forceert elke vlag uit; Normal mode gebruikt de expliciete set, of `allEnabled()` wanneer er geen wordt geleverd).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	Gegooid wanneer een named/pseudo `@page`-regel de paginageometrie verandert.

Diagnostische waarschuwingscodes verschijnen via het adviseringskanaal van het renderresultaat: HTML_RUNNING_ELEMENT_DEGRADED, de HTML_RUNNING_ELEMENT_*-familie en de HTML_PAGE_FLOAT_*-familie.

Codevoorbeeld — Snelle start

Schakel named strings in voor een running header die het huidige hoofdstuk volgt.

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

Codevoorbeeld — Productie

Schakel meerdere vlaggen samen in, en behandel het adviseringskanaal als een signaal dat een constructie is gedegradeerd. De vlaggen zijn onafhankelijk; zet alleen de vlaggen aan die je gebruikt.

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

Randgevallen en valkuilen

Alle vier vlaggen zijn onafhankelijk en standaard uit. Een uitgeschakelde vlag levert byte-identieke uitvoer. Schakel alleen in wat je gebruikt.
string() is leeg wanneer runningStrings uit is, by design. Er is geen waarschuwing voor het uit-geval; het is de gedocumenteerde standaard.
Running elements spelen alleen tekst opnieuw af. Afbeeldingen en geneste blokken binnen een running element worden verwijderd met HTML_RUNNING_ELEMENT_DEGRADED. Controleer het adviseringskanaal.
Named pages kunnen de geometrie niet veranderen. Een geometriewijzigende named/pseudo @page-regel gooit UnsupportedNamedPageException. Stel het paginaformaat en de rotatie in via Config, niet via een named @page-regel.
Page floats houden links in de flow. Een gefloat vak dat een linkannotatie bevat, valt terug op normale flow met een HTML_PAGE_FLOAT_*-diagnostiek, omdat de linkrechthoek gebonden is aan zijn flowpositie.

Prestaties

Elke functie voegt een begrensde hoeveelheid single-pass-werk toe: named strings leggen één waarde per string-set-element vast; named pages voegen een margevakoplossing per pagina toe; running elements leggen één tekstbuffer per geparkeerd element vast; page floats reserveren één band per pagina. Geen ervan houdt een documentboom vast, dus het O(nestingsdiepte)-geheugenmodel van de streamingrenderer blijft behouden. Het performance_budget per pagina (wall_ms: 1500, peak_mb: 64) is onveranderd.

Beveiligingsnotities

Deze vlaggen verbreden het invoeroppervlak niet. Het HTML-beveiligingsbeleid, de CSS-eigenschappenallowlist en de stylesheet-byte- en nestingcaps gelden onveranderd. Vastgelegde string- en elementcontent wordt geëscaped via hetzelfde uitvoerpad als elke andere tekst. De functies voegen lay-outgedrag toe, geen nieuw ingestiekanaal.

Conformiteit

Statement	Spec	Clause
`string-set` legt een named string vast; `string()` lost die op in een paginamargevak.	W3C CSS Generated Content for Paged Media	§3
`position: running()` haalt een element uit de flow; `content: element()` speelt het opnieuw af.	W3C CSS Generated Content for Paged Media	§5
De `page`-eigenschap en `@page <ident>` selecteren een named page-context.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` floatt een vak in de blokas naar een paginaband.	W3C CSS Page Floats Level 3	§5

Dit zijn previewimplementaties van werkgroep-modulefuncties. NextPDF implementeert een single-pass-subset met de hierboven gedocumenteerde fail-closed-grenzen. De geverifieerde status per eigenschap wordt bijgehouden in de CSS-ondersteuningsmatrix; hier wordt geen end-to-end-conformiteit geclaimd. Er wordt geen standaardtekst gereproduceerd.