stabilità: Sperimentale

Flag di anteprima CSS dei paged-media (contenuti correnti GCPM, pagine nominate, page float)

In sintesi

Anteprima opt-in. Queste quattro funzionalità CSS sono disattivate per impostazione predefinita. Quando il flag è spento, il motore produce un output byte-identico a una build che non ha mai conosciuto l’esistenza della funzionalità. Attiva una funzionalità solo quando la vuoi e convalida il risultato per i tuoi documenti.

Il renderer HTML aggiunge quattro funzionalità opt-in dei paged-media dei moduli CSS Paged Media e Generated Content for Paged Media (GCPM). Ciascuna è un flag distinto su CssFeatureFlags. Ciascuna comporta un confine fail-closed onesto: un costrutto che il motore a passaggio singolo non può risolvere fedelmente viene scartato o degradato con una diagnostica nominata, mai reso in modo errato.

Funzionalità	Flag	Cosa fa quando è attiva
Stringhe nominate (GCPM)	`runningStrings`	Acquisizione di `string-set` più `string()` nei margin box di `@page` — intestazioni e piè di pagina correnti.
Pagine nominate (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, la proprietà `page:` e `:first` / `:left` / `:right` / `:blank` — margin box e decorazione per pagina.
Elementi correnti (GCPM)	`runningElements`	`position: running(<ident>)` più `content: element(<ident>)` — riproduce il testo di un elemento in un margin box.
Page float (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — sposta un box nella banda superiore o inferiore della pagina.

Installazione

composer require nextpdf/core:^3

I flag sono inclusi nel pacchetto core. La superficie pubblica CssFeatureFlags è @since 6.1.0. La versione del motore (Version::VERSION) è invariata; queste funzionalità sono additive e disattivate per impostazione predefinita.

Panoramica concettuale

Il renderer è a passaggio singolo e in streaming (vedi ADR-001). Non mantiene alcun albero del documento e scrive l’output una sola volta nell’ordine del documento. Questo vincolo plasma ogni funzionalità qui presente. Ogni funzionalità risolve ciò che può vedere in un singolo passaggio in avanti e fallisce in modo fail-closed su qualsiasi cosa richieda un secondo passaggio o un albero mantenuto. Il confine è documentato, non nascosto — sapere dove una funzionalità si ferma fa parte del suo utilizzo.

Abiliti una funzionalità costruendo CssFeatureFlags con il flag impostato a true e passandolo a Config. Quando un flag è spento, il CSS corrispondente viene analizzato e ignorato esattamente come avverrebbe per una proprietà non supportata, perciò l’output è byte-identico a una build senza la funzionalità.

Stringhe nominate — `runningStrings`

string-set: <ident> content() registra un valore mentre il motore passa sull’elemento. Un riferimento string(<ident>) all’interno di un margin box di @page si risolve poi al valore più recente visto su quella pagina. Questo è il meccanismo standard per un’intestazione corrente che segue il capitolo o la sezione attuale.

La risoluzione è a passaggio singolo “ultimo visto su questa pagina”. Un riferimento string() si risolve all’ultimo valore registrato dal motore prima di disporre i margin box di quella pagina.

Confine fail-closed. Con il flag spento, string() si risolve alla stringa vuota e l’output resta byte-identico. Una lista di contenuti string-set malformata scarta quella singola coppia di assegnazione e prosegue; non interrompe mai il render.

Pagine nominate — `namedPagesAdvanced`

La proprietà page: <ident> assegna un elemento a un contesto di pagina nominata, e una regola @page <ident> corrispondente fornisce i margin box e la decorazione di pagina di quel contesto. Le pseudo-classi di pagina :first, :left, :right e :blank selezionano la prima pagina, le pagine recto e verso e le pagine intenzionalmente vuote.

Questa funzionalità seleziona i margin box e la decorazione di una pagina nominata o pseudo. Non modifica la geometria della pagina.

Confine fail-closed. Una regola @page nominata o pseudo che tenta di modificare la geometria — size, rotate o un margine del content-box che ridimensiona l’area di pagina — fallisce in modo fail-closed con UnsupportedNamedPageException invece di produrre silenziosamente una pagina disallineata. Il canale di matching delle pseudo-classi è la prima fetta; i casi di selettore più ampi sono rinviati e documentati.

Elementi correnti — `runningElements`

position: running(<ident>) rimuove un elemento dal flusso normale e lo parcheggia sotto un nome. content: element(<ident>) in un margin box riproduce poi quell’elemento su ciascuna pagina. Usalo quando un’intestazione necessita del testo completo e stilizzato di un titolo, non solo di una stringa acquisita.

Confine fail-closed. Questa fetta riproduce solo il testo dell’elemento corrente. Il contenuto ricco — immagini, elementi rimpiazzati, struttura a blocco annidata — viene scartato, e il motore emette una diagnostica HTML_RUNNING_ELEMENT_DEGRADED affinché la perdita sia visibile, non silenziosa. Un elemento running() che fa riferimento a sé stesso, un running() annidato o un’acquisizione che supera il budget interno fallisce in modo fail-closed. Con il flag spento, running() ed element() sono inerti.

Page float — `pageFloats`

float: top, float: bottom e float: snap spostano un box nella banda superiore o inferiore della pagina lungo l’asse di blocco, riservando l’altezza della banda affinché il testo circostante rifluisca attorno alla regione riservata.

float: bottom (e snap che si risolve nella banda inferiore) è il caso che il motore a passaggio singolo gestisce direttamente: il box viene acquisito e collocato nella banda inferiore della pagina alla chiusura della pagina. float: top degenera nella banda superiore della pagina.

Confine fail-closed. Lo snap lungo l’asse inline (snap-inline) non è supportato. Un box che comporta un effetto collaterale non spostabile — per esempio un’annotazione di link, il cui rettangolo è vincolato alla sua posizione nel flusso — non può essere riposizionato in modo sicuro, perciò ricade nel flusso normale e il motore emette una diagnostica HTML_PAGE_FLOAT_* che spiega il fallback. Con il flag spento, float: top | bottom | snap è trattato come un valore non supportato e ignorato.

Superficie API

Simbolo	Posizione	Ruolo
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	Insieme di flag opt-in immutabile; il costruttore accetta `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` (tutti `false` per impostazione predefinita).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Collega l’insieme di flag alla configurazione di un documento.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	Risolve un insieme di flag per una modalità di rendering (la modalità Safe forza ogni flag a spento; la modalità Normal usa l’insieme esplicito, oppure `allEnabled()` quando nessuno è fornito).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	Sollevata quando una regola `@page` nominata/pseudo modifica la geometria della pagina.

I codici di avviso diagnostico emergono attraverso il canale di avviso del risultato di render: HTML_RUNNING_ELEMENT_DEGRADED, la famiglia HTML_RUNNING_ELEMENT_* e la famiglia HTML_PAGE_FLOAT_*.

Esempio di codice — Avvio rapido

Abilita le stringhe nominate per un’intestazione corrente che segue il capitolo attuale.

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

Esempio di codice — Produzione

Abilita più flag insieme e tratta il canale di avviso come segnale che un costrutto è stato degradato. I flag sono indipendenti; attiva solo quelli che usi.

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

Casi limite e insidie

Tutti e quattro i flag sono indipendenti e disattivati per impostazione predefinita. Un flag spento produce un output byte-identico. Abilita solo ciò che usi.
string() è vuoto quando runningStrings è spento, per progettazione. Non c’è alcun avviso per il caso spento; è l’impostazione predefinita documentata.
Gli elementi correnti riproducono solo il testo. Immagini e blocchi annidati all’interno di un elemento corrente vengono scartati con HTML_RUNNING_ELEMENT_DEGRADED. Controlla il canale di avviso.
Le pagine nominate non possono modificare la geometria. Una regola @page nominata/pseudo che modifica la geometria solleva UnsupportedNamedPageException. Imposta dimensione e rotazione della pagina tramite Config, non tramite una regola @page nominata.
I page float mantengono i link nel flusso. Un box flottato che contiene un’annotazione di link ricade nel flusso normale con una diagnostica HTML_PAGE_FLOAT_*, perché il rettangolo del link è vincolato alla sua posizione nel flusso.

Prestazioni

Ogni funzionalità aggiunge una quantità limitata di lavoro a passaggio singolo: le stringhe nominate registrano un valore per ogni elemento string-set; le pagine nominate aggiungono una risoluzione dei margin box per pagina; gli elementi correnti acquisiscono un buffer di testo per ogni elemento parcheggiato; i page float riservano una banda per pagina. Nessuna mantiene un albero del documento, perciò il modello di memoria O(profondità di annidamento) del renderer in streaming è preservato. Il performance_budget per pagina (wall_ms: 1500, peak_mb: 64) è invariato.

Note sulla sicurezza

Questi flag non ampliano la superficie di input. La policy di sicurezza HTML, l’allowlist delle proprietà CSS e i limiti di byte del foglio di stile e di annidamento si applicano invariati. Il contenuto di stringhe ed elementi acquisito è sottoposto a escape attraverso lo stesso percorso di output di qualsiasi altro testo. Le funzionalità aggiungono comportamento di layout, non un nuovo canale di ingestione.

Conformità

Affermazione	Standard	Clausola
`string-set` registra una stringa nominata; `string()` la risolve in un margin box di pagina.	W3C CSS Generated Content for Paged Media	§3
`position: running()` rimuove un elemento dal flusso; `content: element()` lo riproduce.	W3C CSS Generated Content for Paged Media	§5
La proprietà `page` e `@page <ident>` selezionano un contesto di pagina nominata.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` flotta un box lungo l’asse di blocco verso una banda di pagina.	W3C CSS Page Floats Level 3	§5

Queste sono implementazioni di anteprima di funzionalità di moduli in fase di working-group. NextPDF implementa un sottoinsieme a passaggio singolo con i confini fail-closed documentati sopra. Lo stato verificato per ogni proprietà è tracciato nella matrice di supporto CSS; qui non si rivendica alcuna conformità end-to-end. Nessun testo normativo è riprodotto.