Flag preview CSS paged-media (konten berjalan GCPM, halaman bernama, page float)

Sekilas

Preview opt-in. Keempat fitur CSS ini default-mati. Saat flag mati, mesin menghasilkan keluaran yang byte-identik dengan build yang tidak pernah mengenal fitur tersebut. Aktifkan sebuah fitur hanya saat Anda menginginkannya, dan validasi hasilnya untuk dokumen Anda.

Perender HTML menambahkan empat fitur paged-media opt-in dari modul CSS Paged Media dan Generated Content for Paged Media (GCPM). Masing-masing adalah flag tersendiri pada CssFeatureFlags. Masing-masing membawa batasan fail-closed yang jujur: konstruksi yang tidak dapat diselesaikan mesin satu-lintasan secara setia akan digugurkan atau diturunkan dengan diagnostik bernama, tidak pernah dirender keliru.

Fitur	Flag	Apa yang dilakukannya saat aktif
Named string (GCPM)	runningStrings	Penangkapan string-set plus string() di margin box @page — header dan footer berjalan.
Halaman bernama (Paged Media L3)	namedPagesAdvanced	@page <ident>, properti page:, dan :first / :left / :right / :blank — margin box dan dekorasi per-halaman.
Running element (GCPM)	runningElements	position: running(<ident>) plus content: element(<ident>) — memutar ulang teks sebuah elemen di margin box.
Page float (Page Floats L3)	pageFloats	float: top | bottom | snap — memindahkan sebuah box ke band atas atau bawah halaman.

Pemasangan

composer require nextpdf/core:^3

Flag tersebut disertakan dalam paket core. Permukaan publik CssFeatureFlags adalah @since 6.1.0. Versi mesin (Version::VERSION) tidak berubah; fitur-fitur ini bersifat aditif dan default-mati.

Ikhtisar konseptual

Perender bersifat satu-lintasan dan streaming (lihat ADR-001). Perender tidak menyimpan pohon dokumen dan menulis keluaran sekali saja dalam urutan dokumen. Batasan tersebut membentuk setiap fitur di sini. Setiap fitur menyelesaikan apa yang dapat dilihatnya dalam satu lintasan maju dan gagal secara fail-closed pada apa pun yang memerlukan lintasan kedua atau pohon yang dipertahankan. Batasnya didokumentasikan, bukan disembunyikan — mengetahui di mana sebuah fitur berhenti adalah bagian dari penggunaannya.

Anda mengaktifkan sebuah fitur dengan mengonstruksi CssFeatureFlags dengan flag disetel ke true dan meneruskannya ke Config. Saat sebuah flag mati, CSS yang bersangkutan diurai dan diabaikan persis seperti properti yang tidak didukung, sehingga keluarannya byte-identik dengan build tanpa fitur tersebut.

Named string — runningStrings

string-set: <ident> content() merekam sebuah nilai saat mesin melewati elemen. Sebuah referensi string(<ident>) di dalam margin box @page lalu menyelesaikan ke nilai terakhir yang terlihat pada halaman itu. Ini adalah mekanisme standar untuk header berjalan yang melacak bab atau bagian saat ini.

Penyelesaiannya satu-lintasan “terakhir terlihat pada halaman ini”. Sebuah referensi string() diselesaikan ke nilai terakhir yang direkam mesin sebelum ia menata margin box halaman tersebut.

Batasan fail-closed. Dengan flag mati, string() diselesaikan ke string kosong dan keluaran tetap byte-identik. Daftar konten string-set yang malformed menggugurkan satu pasangan penetapan itu dan melanjutkan; ia tidak pernah membatalkan render.

Halaman bernama — namedPagesAdvanced

Properti page: <ident> menetapkan sebuah elemen ke konteks halaman bernama, dan aturan @page <ident> yang cocok menyediakan margin box dan dekorasi halaman bagi konteks itu. Pseudo-class halaman :first, :left, :right, dan :blank memilih halaman pertama, halaman recto dan verso, serta halaman yang sengaja dikosongkan.

Fitur ini memilih margin box dan dekorasi suatu halaman bernama atau pseudo. Ia tidak mengubah geometri halaman.

Batasan fail-closed. Aturan @page bernama atau pseudo yang mencoba mengubah geometri — size, rotate, atau margin content-box yang mengubah ukuran area halaman — gagal secara fail-closed dengan UnsupportedNamedPageException alih-alih diam-diam menghasilkan halaman yang misalign. Kanal pencocokan pseudo-class adalah irisan pertama; kasus selektor yang lebih luas ditangguhkan dan didokumentasikan.

Running element — runningElements

position: running(<ident>) mengeluarkan sebuah elemen dari aliran normal dan memarkirnya di bawah sebuah nama. content: element(<ident>) di margin box lalu memutar ulang elemen itu pada setiap halaman. Gunakan saat sebuah header membutuhkan teks bergaya penuh dari sebuah heading, bukan sekadar string yang ditangkap.

Batasan fail-closed. Irisan ini hanya memutar ulang teks dari running element. Konten kaya — gambar, replaced element, struktur blok bersarang — digugurkan, dan mesin memancarkan diagnostik HTML_RUNNING_ELEMENT_DEGRADED sehingga kehilangan itu terlihat, bukan diam-diam. Sebuah elemen running() yang mereferensikan dirinya sendiri, sebuah running() bersarang, atau penangkapan yang melampaui anggaran internal akan gagal secara fail-closed. Dengan flag mati, running() dan element() bersifat inert.

Page float — pageFloats

float: top, float: bottom, dan float: snap memindahkan sebuah box ke band atas atau bawah halaman pada sumbu blok, mencadangkan tinggi band sehingga teks di sekitarnya mengalir ulang di sekeliling region yang dicadangkan.

float: bottom (dan snap yang teratasi ke band bawah) adalah kasus yang ditangani langsung oleh mesin satu-lintasan: box ditangkap dan ditempatkan di band bawah halaman saat halaman ditutup. float: top terdegenerasi menjadi band atas-halaman.

Batasan fail-closed. snap pada sumbu inline (snap-inline) tidak didukung. Sebuah box yang membawa efek samping yang tidak dapat dipindahkan — misalnya anotasi tautan, yang persegi panjangnya terikat pada posisi alirannya — tidak dapat direlokasi dengan aman, sehingga ia kembali ke aliran normal dan mesin memancarkan diagnostik HTML_PAGE_FLOAT_* yang menjelaskan fallback tersebut. Dengan flag mati, float: top | bottom | snap diperlakukan sebagai nilai yang tidak didukung dan diabaikan.

Permukaan API

Simbol	Lokasi	Peran
CssFeatureFlags	src/Html/CssFeatureFlags.php	Kumpulan flag opt-in yang immutable; konstruktor menerima runningStrings, namedPagesAdvanced, runningElements, pageFloats (semua default false).
Config::withCssFeatureFlags(CssFeatureFlags $flags): self	src/Core/Config.php	Melampirkan kumpulan flag ke konfigurasi dokumen.
CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self	src/Html/CssFeatureFlags.php	Menyelesaikan kumpulan flag untuk mode rendering (mode Safe memaksa setiap flag mati; mode Normal memakai kumpulan eksplisit, atau allEnabled() saat tidak ada yang disuplai).
UnsupportedNamedPageException	src/Html/PagedMedia/UnsupportedNamedPageException.php	Dilempar saat aturan @page bernama/pseudo mengubah geometri halaman.

Kode peringatan diagnostik muncul melalui kanal advisory pada hasil render: HTML_RUNNING_ELEMENT_DEGRADED, keluarga HTML_RUNNING_ELEMENT_*, dan keluarga HTML_PAGE_FLOAT_*.

Contoh kode — Mulai cepat

Aktifkan named string untuk header berjalan yang melacak bab saat ini.

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

Contoh kode — Produksi

Aktifkan beberapa flag sekaligus, dan perlakukan kanal advisory sebagai sinyal bahwa sebuah konstruksi terdegradasi. Flag bersifat independen; aktifkan hanya yang Anda pakai.

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

Kasus tepi & jebakan

• Keempat flag bersifat independen dan default-mati. Flag yang mati menghasilkan keluaran byte-identik. Aktifkan hanya yang Anda pakai.
• string() kosong saat runningStrings mati, sesuai rancangan. Tidak ada peringatan untuk kasus mati; itu adalah default yang terdokumentasi.
• Running element hanya memutar ulang teks. Gambar dan blok bersarang di dalam running element digugurkan dengan HTML_RUNNING_ELEMENT_DEGRADED. Periksa kanal advisory.
• Halaman bernama tidak dapat mengubah geometri. Aturan @page bernama/pseudo yang mengubah geometri melempar UnsupportedNamedPageException. Setel ukuran dan rotasi halaman melalui Config, bukan melalui aturan @page bernama.
• Page float menjaga tautan tetap dalam aliran. Box yang di-float yang berisi anotasi tautan kembali ke aliran normal dengan diagnostik HTML_PAGE_FLOAT_*, karena persegi panjang tautan terikat pada posisi alirannya.

Kinerja

Setiap fitur menambah sejumlah pekerjaan satu-lintasan yang terbatas: named string merekam satu nilai per elemen string-set; halaman bernama menambah penyelesaian margin-box per-halaman; running element menangkap satu buffer teks per elemen yang diparkir; page float mencadangkan satu band per halaman. Tidak ada yang mempertahankan pohon dokumen, sehingga model memori O(kedalaman bersarang) dari perender streaming tetap terjaga. performance_budget per-halaman (wall_ms: 1500, peak_mb: 64) tidak berubah.

Catatan keamanan

Flag-flag ini tidak memperlebar permukaan masukan. Kebijakan keamanan HTML, allowlist properti CSS, serta cap byte stylesheet dan kedalaman bersarang berlaku tanpa perubahan. Konten string dan elemen yang ditangkap di-escape melalui jalur keluaran yang sama dengan teks lainnya. Fitur ini menambahkan perilaku tata letak, bukan kanal ingesti baru.

Konformitas

Pernyataan	Standar	Klausul
string-set merekam sebuah named string; string() menyelesaikannya di margin box halaman.	W3C CSS Generated Content for Paged Media	§3
position: running() mengeluarkan elemen dari aliran; content: element() memutarnya ulang.	W3C CSS Generated Content for Paged Media	§5
Properti page dan @page <ident> memilih konteks halaman bernama.	W3C CSS Paged Media Module Level 3	§3
float: top | bottom | snap mem-float sebuah box pada sumbu blok ke band halaman.	W3C CSS Page Floats Level 3	§5

Ini adalah implementasi preview dari fitur modul kelompok kerja. NextPDF mengimplementasikan subset satu-lintasan dengan batasan fail-closed yang terdokumentasi di atas. Status terverifikasi per-properti dilacak dalam matriks dukungan CSS; tidak ada konformitas ujung-ke-ujung yang diklaim di sini. Tidak ada teks standar yang direproduksi.

Lihat juga

• Subsistem rendering HTML
• Batasan streaming satu-lintasan (ADR-001)
• Tata letak mode-dipertahankan (grid-template-areas)
• Modul Config
• Matriks dukungan CSS