stabilność: Eksperymentalna

Flagi podglądowe CSS Paged-media (treść bieżąca GCPM, strony nazwane, page floats)

W skrócie

Opcjonalny podgląd. Te cztery funkcje CSS są domyślnie wyłączone. Gdy flaga jest wyłączona, silnik wytwarza wynik bajtowo identyczny z kompilacją, która nigdy nie znała tej funkcji. Włączaj funkcję tylko wtedy, gdy jej chcesz, i waliduj wynik dla swoich dokumentów.

Renderer HTML dodaje cztery opcjonalne funkcje paged-media z modułów CSS Paged Media oraz Generated Content for Paged Media (GCPM). Każda z nich to osobna flaga w CssFeatureFlags. Każda niesie uczciwą granicę fail-closed: konstrukcja, której jednoprzebiegowy silnik nie potrafi rozwiązać wiernie, jest pomijana lub degradowana z nazwaną diagnostyką, nigdy nie renderowana błędnie.

Funkcja	Flaga	Co robi po włączeniu
Bieżące łańcuchy znaków (GCPM)	`runningStrings`	Przechwytywanie `string-set` oraz `string()` w polach marginesowych `@page` — bieżące nagłówki i stopki.
Strony nazwane (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, właściwość `page:` oraz `:first` / `:left` / `:right` / `:blank` — pola marginesowe i dekoracja na poszczególnych stronach.
Elementy bieżące (GCPM)	`runningElements`	`position: running(<ident>)` oraz `content: element(<ident>)` — odtworzenie tekstu elementu w polu marginesowym.
Page floats (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — przeniesienie ramki do górnego lub dolnego pasma strony.

Instalacja

composer require nextpdf/core:^3

Flagi są dostarczane w pakiecie core. Publiczna powierzchnia CssFeatureFlags to @since 6.1.0. Wersja silnika (Version::VERSION) pozostaje bez zmian; te funkcje są addytywne i domyślnie wyłączone.

Przegląd koncepcyjny

Renderer jest jednoprzebiegowy i strumieniowy (zob. ADR-001). Nie utrzymuje drzewa dokumentu i zapisuje wynik raz, w kolejności dokumentu. To ograniczenie kształtuje każdą funkcję na tej stronie. Każda funkcja rozwiązuje to, co widzi w jednym przebiegu naprzód, i kończy się niepowodzeniem fail-closed przy wszystkim, co wymagałoby drugiego przebiegu lub zachowanego drzewa. Granica jest udokumentowana, a nie ukryta — wiedza o tym, gdzie funkcja się kończy, to część jej używania.

Funkcję włącza się, konstruując CssFeatureFlags z flagą ustawioną na true i przekazując ją do Config. Gdy flaga jest wyłączona, odpowiadający jej CSS jest parsowany i ignorowany dokładnie tak, jak nieobsługiwana właściwość, więc wynik jest bajtowo identyczny z kompilacją bez tej funkcji.

Bieżące łańcuchy znaków — `runningStrings`

string-set: <ident> content() zapisuje wartość, gdy silnik mija element. Odwołanie string(<ident>) wewnątrz pola marginesowego @page rozwiązuje się następnie do najświeższej wartości zaobserwowanej na tej stronie. To standardowy mechanizm dla bieżącego nagłówka śledzącego bieżący rozdział lub sekcję.

Rozwiązywanie jest jednoprzebiegowe — „ostatnia zaobserwowana na tej stronie”. Odwołanie string() rozwiązuje się do ostatniej wartości zapisanej przez silnik, zanim rozłożył pola marginesowe tej strony.

Granica fail-closed. Przy wyłączonej fladze string() rozwiązuje się do pustego łańcucha, a wynik pozostaje bajtowo identyczny. Wadliwa lista treści string-set pomija jedną parę przypisania i kontynuuje; nigdy nie przerywa renderowania.

Strony nazwane — `namedPagesAdvanced`

Właściwość page: <ident> przypisuje element do nazwanego kontekstu strony, a pasująca reguła @page <ident> dostarcza pola marginesowe i dekorację strony dla tego kontekstu. Pseudoklasy stron :first, :left, :right i :blank wybierają pierwszą stronę, strony recto i verso oraz strony celowo puste.

Ta funkcja wybiera pola marginesowe i dekorację strony nazwanej lub pseudostrony. Nie zmienia geometrii strony.

Granica fail-closed. Nazwana lub pseudoreguła @page, która próbuje zmienić geometrię — size, rotate lub margines pudełka treści zmieniający rozmiar obszaru strony — kończy się niepowodzeniem fail-closed z UnsupportedNamedPageException, zamiast po cichu wytworzyć źle wyrównaną stronę. Kanał dopasowania pseudoklas to pierwsza warstwa; szersze przypadki selektorów są odroczone i udokumentowane.

Elementy bieżące — `runningElements`

position: running(<ident>) usuwa element z normalnego przepływu i parkuje go pod nazwą. content: element(<ident>) w polu marginesowym odtwarza następnie ten element na każdej stronie. Używaj go, gdy nagłówek potrzebuje pełnego, ostylowanego tekstu nagłówka, a nie tylko przechwyconego łańcucha.

Granica fail-closed. Ta warstwa odtwarza wyłącznie tekst elementu bieżącego. Treść bogata — obrazy, elementy zastępcze, zagnieżdżona struktura blokowa — jest pomijana, a silnik emituje diagnostykę HTML_RUNNING_ELEMENT_DEGRADED, dzięki czemu strata jest widoczna, a nie ukryta. Element running(), który odwołuje się do samego siebie, zagnieżdżony running() lub przechwycenie przekraczające budżet wewnętrzny kończą się niepowodzeniem fail-closed. Przy wyłączonej fladze running() i element() są bezczynne.

Page floats — `pageFloats`

float: top, float: bottom i float: snap przenoszą ramkę do górnego lub dolnego pasma strony w osi blokowej, rezerwując wysokość pasma, tak aby otaczający tekst opływał zarezerwowany obszar.

float: bottom (oraz snap rozwiązujący się do dolnego pasma) to przypadek, który jednoprzebiegowy silnik obsługuje bezpośrednio: ramka jest przechwytywana i umieszczana w dolnym paśmie strony w momencie zamykania strony. float: top degeneruje się do pasma górnej części strony.

Granica fail-closed. snap w osi liniowej (snap-inline) nie jest obsługiwany. Ramka niosąca nieprzemieszczalny efekt uboczny — na przykład adnotacja łącza, której prostokąt jest związany z jej pozycją w przepływie — nie może zostać bezpiecznie przeniesiona, więc wraca do normalnego przepływu, a silnik emituje diagnostykę HTML_PAGE_FLOAT_* wyjaśniającą to wycofanie. Przy wyłączonej fladze float: top | bottom | snap jest traktowany jako nieobsługiwana wartość i ignorowany.

Powierzchnia API

Symbol	Lokalizacja	Rola
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	Niezmienialny opcjonalny zestaw flag; konstruktor przyjmuje `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` (wszystkie domyślnie `false`).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Dołącza zestaw flag do konfiguracji dokumentu.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	Rozwiązuje zestaw flag dla trybu renderowania (tryb Safe wymusza wyłączenie każdej flagi; tryb Normal używa jawnego zestawu albo `allEnabled()`, gdy żaden nie został podany).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	Zgłaszany, gdy nazwana/pseudoreguła `@page` zmienia geometrię strony.

Kody ostrzeżeń diagnostycznych wypływają przez kanał doradczy wyniku renderowania: HTML_RUNNING_ELEMENT_DEGRADED, rodzina HTML_RUNNING_ELEMENT_* oraz rodzina HTML_PAGE_FLOAT_*.

Przykład kodu — szybki start

Włącz bieżące łańcuchy znaków dla bieżącego nagłówka śledzącego bieżący rozdział.

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

Przykład kodu — produkcja

Włącz kilka flag jednocześnie i traktuj kanał doradczy jako sygnał, że konstrukcja uległa degradacji. Flagi są niezależne; włączaj tylko te, których używasz.

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

Przypadki brzegowe i pułapki

Wszystkie cztery flagi są niezależne i domyślnie wyłączone. Wyłączona flaga daje wynik bajtowo identyczny. Włączaj tylko to, czego używasz.
string() jest puste, gdy runningStrings jest wyłączone, zgodnie z założeniem. Dla przypadku wyłączonego nie ma ostrzeżenia; to udokumentowane zachowanie domyślne.
Elementy bieżące odtwarzają tylko tekst. Obrazy i zagnieżdżone bloki wewnątrz elementu bieżącego są pomijane z HTML_RUNNING_ELEMENT_DEGRADED. Sprawdź kanał doradczy.
Strony nazwane nie mogą zmieniać geometrii. Nazwana/pseudoreguła @page zmieniająca geometrię zgłasza UnsupportedNamedPageException. Ustaw rozmiar i obrót strony przez Config, a nie przez nazwaną regułę @page.
Page floats utrzymują łącza w przepływie. Pływająca ramka zawierająca adnotację łącza wraca do normalnego przepływu z diagnostyką HTML_PAGE_FLOAT_*, ponieważ prostokąt łącza jest związany z jego pozycją w przepływie.

Wydajność

Każda funkcja dodaje ograniczoną ilość pracy jednoprzebiegowej: bieżące łańcuchy znaków zapisują jedną wartość na element string-set; strony nazwane dodają rozwiązywanie pól marginesowych na każdą stronę; elementy bieżące przechwytują jeden bufor tekstu na zaparkowany element; page floats rezerwują jedno pasmo na stronę. Żadna nie zachowuje drzewa dokumentu, więc model pamięci O(głębokość zagnieżdżenia) renderera strumieniowego zostaje zachowany. Budżet performance_budget na stronę (wall_ms: 1500, peak_mb: 64) pozostaje bez zmian.

Uwagi dotyczące bezpieczeństwa

Te flagi nie poszerzają powierzchni wejściowej. Polityka bezpieczeństwa HTML, lista dozwolonych właściwości CSS oraz limity bajtów arkusza stylów i głębokości zagnieżdżenia obowiązują bez zmian. Przechwycona treść łańcuchów i elementów jest escapowana tą samą ścieżką wyjściową co każdy inny tekst. Funkcje dodają zachowanie układu, a nie nowy kanał wczytywania.

Zgodność

Twierdzenie	Norma	Klauzula
`string-set` zapisuje nazwany łańcuch; `string()` rozwiązuje go w polu marginesowym strony.	W3C CSS Generated Content for Paged Media	§3
`position: running()` usuwa element z przepływu; `content: element()` go odtwarza.	W3C CSS Generated Content for Paged Media	§5
Właściwość `page` oraz `@page <ident>` wybierają nazwany kontekst strony.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` przenosi ramkę w osi blokowej do pasma strony.	W3C CSS Page Floats Level 3	§5

To podglądowe implementacje funkcji modułów grupy roboczej. NextPDF implementuje jednoprzebiegowy podzbiór z udokumentowanymi powyżej granicami fail-closed. Status zweryfikowania poszczególnych właściwości jest śledzony w macierzy wsparcia CSS; nie deklaruje się tu zgodności end-to-end. Nie odtwarza się żadnego tekstu normatywnego.