kararlılık: Deneysel

Sayfalı medya CSS önizleme bayrakları (GCPM çalışan içerik, adlandırılmış sayfalar, sayfa float'ları)

Bir bakışta

Katılımlı önizleme. Bu dört CSS özelliği varsayılan olarak kapalıdır. Bayrak kapalı olduğunda motor, özelliğin var olduğunu hiç bilmeyen bir derlemeyle bayt düzeyinde özdeş çıktı üretir. Bir özelliği yalnızca istediğinizde açın ve sonucu kendi belgeleriniz için doğrulayın.

HTML işleyicisi, CSS Paged Media ve Generated Content for Paged Media (GCPM) modüllerinden dört adet katılımlı sayfalı medya özelliği ekler. Her biri CssFeatureFlags üzerinde ayrı bir bayraktır. Her biri dürüst bir hata-durumunda-kapalı sınırı taşır: tek geçişli motorun aslına uygun çözemediği bir yapı, adlandırılmış bir tanılama ile düşürülür veya bozularak sunulur; asla yanlış işlenmez.

Özellik	Bayrak	Açık olduğunda ne yapar
Adlandırılmış dizeler (GCPM)	`runningStrings`	`@page` kenar boşluğu kutularında `string-set` yakalaması ve `string()` — çalışan üst bilgiler ve alt bilgiler.
Adlandırılmış sayfalar (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, `page:` özelliği ve `:first` / `:left` / `:right` / `:blank` — sayfa başına kenar boşluğu kutuları ve süsleme.
Çalışan öğeler (GCPM)	`runningElements`	`position: running(<ident>)` ve `content: element(<ident>)` — bir öğenin metnini bir kenar boşluğu kutusunda yeniden oynatır.
Sayfa float’ları (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — bir kutuyu sayfanın üst veya alt bandına taşır.

Kurulum

composer require nextpdf/core:^3

Bayraklar core paketiyle birlikte gelir. CssFeatureFlags genel yüzeyi @since 6.1.0 şeklindedir. Motor sürümü (Version::VERSION) değişmez; bu özellikler eklemelidir ve varsayılan olarak kapalıdır.

Kavramsal genel bakış

İşleyici tek geçişli ve akıştır (bkz. ADR-001). Hiçbir belge ağacı tutmaz ve çıktıyı bir kez, belge sırasına göre yazar. Bu kısıt, buradaki her özelliği biçimlendirir. Her özellik, tek bir ileri geçişte görebildiğini çözer ve ikinci bir geçiş ya da korunan bir ağaç gerektirecek her şeyde hata durumunda kapalı kalır. Sınır gizlenmez, belgelenir — bir özelliğin nerede durduğunu bilmek, onu kullanmanın bir parçasıdır.

Bir özelliği, CssFeatureFlags öğesini ilgili bayrak true olarak ayarlanmış biçimde oluşturup Config öğesine geçirerek etkinleştirirsiniz. Bir bayrak kapalı olduğunda, ilgili CSS desteklenmeyen bir özellik gibi ayrıştırılır ve yok sayılır; böylece çıktı, özelliği içermeyen bir derlemeyle bayt düzeyinde özdeştir.

Adlandırılmış dizeler — `runningStrings`

string-set: <ident> content(), motor öğeden geçerken bir değeri kaydeder. Bir @page kenar boşluğu kutusunun içindeki bir string(<ident>) başvurusu, o zaman o sayfada görülen en son değere çözümlenir. Bu, geçerli bölümü ya da kesimi izleyen çalışan bir üst bilgi için standart mekanizmadır.

Çözümleme tek geçişlidir, “bu sayfada en son görülen”. Bir string() başvurusu, motorun o sayfanın kenar boşluğu kutularını yerleştirmeden önce kaydettiği son değere çözümlenir.

Hata-durumunda-kapalı sınırı. Bayrak kapalıyken string(), boş dizeye çözümlenir ve çıktı bayt düzeyinde özdeş kalır. Bozuk biçimli bir string-set içerik listesi yalnızca o tek atama çiftini düşürür ve devam eder; işlemeyi asla yarıda kesmez.

Adlandırılmış sayfalar — `namedPagesAdvanced`

page: <ident> özelliği bir öğeyi adlandırılmış bir sayfa bağlamına atar ve eşleşen bir @page <ident> kuralı, o bağlamın kenar boşluğu kutularını ve sayfa süslemesini sağlar. :first, :left, :right ve :blank sayfa sözde sınıfları sırasıyla ilk sayfayı, recto ve verso sayfaları ile kasıtlı olarak boş bırakılan sayfaları seçer.

Bu özellik, adlandırılmış ya da sözde bir sayfanın kenar boşluğu kutularını ve süslemesini seçer. Sayfa geometrisini değiştirmez.

Hata-durumunda-kapalı sınırı. Geometriyi değiştirmeye çalışan adlandırılmış ya da sözde bir @page kuralı — size, rotate ya da sayfa alanını yeniden boyutlandıran bir içerik-kutusu kenar boşluğu — sessizce hizasız bir sayfa üretmek yerine UnsupportedNamedPageException ile hata durumunda kapalı kalır. Sözde sınıf eşleştirme kanalı ilk dilimdir; daha geniş seçici durumları ertelenmiş ve belgelenmiştir.

Çalışan öğeler — `runningElements`

position: running(<ident>), bir öğeyi normal akıştan çıkarır ve onu bir ad altında park eder. Bir kenar boşluğu kutusundaki content: element(<ident>) o zaman her sayfada o öğeyi yeniden oynatır. Bir üst bilginin yalnızca yakalanmış bir dizeye değil, bir başlığın tam biçimlendirilmiş metnine ihtiyaç duyduğunda bunu kullanın.

Hata-durumunda-kapalı sınırı. Bu dilim yalnızca çalışan öğenin metnini yeniden oynatır. Zengin içerik — görüntüler, değiştirilmiş öğeler, iç içe blok yapısı — düşürülür ve motor, kaybın sessiz değil görünür olması için bir HTML_RUNNING_ELEMENT_DEGRADED tanılaması yayar. Kendisine başvuran bir running() öğesi, iç içe bir running() ya da iç bütçeyi aşan bir yakalama, hata durumunda kapalı kalır. Bayrak kapalıyken running() ve element() etkisizdir.

Sayfa float’ları — `pageFloats`

float: top, float: bottom ve float: snap, bir kutuyu blok ekseninde sayfanın üst veya alt bandına taşır ve bandın yüksekliğini ayırır; böylece çevreleyen metin, ayrılan bölgenin etrafından yeniden akar.

float: bottom (ve alt banda çözümlenen snap), tek geçişli motorun doğrudan işlediği durumdur: kutu yakalanır ve sayfa kapanırken sayfanın alt bandına yerleştirilir. float: top, sayfa-üstü bandına indirgenir.

Hata-durumunda-kapalı sınırı. Satır içi eksende snap (snap-inline) desteklenmez. Taşınamayan bir yan etki taşıyan bir kutu — örneğin dikdörtgeni akış konumuna bağlı bir bağlantı ek açıklaması — güvenli biçimde yeniden konumlandırılamaz; bu nedenle normal akışa geri döner ve motor, geri dönüşü açıklayan bir HTML_PAGE_FLOAT_* tanılaması yayar. Bayrak kapalıyken float: top | bottom | snap, desteklenmeyen bir değer olarak ele alınır ve yok sayılır.

API yüzeyi

Simge	Konum	Rol
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	Değişmez katılımlı bayrak kümesi; yapıcı `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` alır (tümü varsayılan `false`).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Bayrak kümesini bir belge yapılandırmasına iliştirir.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	Bir işleme kipi için bir bayrak kümesi çözer (Safe kipi her bayrağı kapalıya zorlar; Normal kipi açıkça verilen kümeyi, hiçbiri verilmediğinde ise `allEnabled()` kullanır).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	Adlandırılmış/sözde bir `@page` kuralı sayfa geometrisini değiştirdiğinde fırlatılır.

Tanılama uyarı kodları, işleme sonucunun danışma kanalı üzerinden yüzeye çıkar: HTML_RUNNING_ELEMENT_DEGRADED, HTML_RUNNING_ELEMENT_* ailesi ve HTML_PAGE_FLOAT_* ailesi.

Kod örneği — hızlı başlangıç

Geçerli bölümü izleyen çalışan bir üst bilgi için adlandırılmış dizeleri etkinleştirin.

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

Kod örneği — üretim

Birkaç bayrağı birlikte etkinleştirin ve danışma kanalını bir yapının bozulduğunu gösteren bir sinyal olarak ele alın. Bayraklar bağımsızdır; yalnızca kullandıklarınızı açın.

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

Sınır durumları ve dikkat edilmesi gerekenler

Dört bayrak da bağımsızdır ve varsayılan olarak kapalıdır. Kapalı bir bayrak bayt düzeyinde özdeş çıktı verir. Yalnızca kullandığınızı etkinleştirin.
runningStrings kapalıyken string() boştur, tasarım gereği. Kapalı durum için bir uyarı yoktur; bu belgelenmiş varsayılandır.
Çalışan öğeler yalnızca metni yeniden oynatır. Çalışan bir öğenin içindeki görüntüler ve iç içe bloklar HTML_RUNNING_ELEMENT_DEGRADED ile düşürülür. Danışma kanalını denetleyin.
Adlandırılmış sayfalar geometriyi değiştiremez. Geometriyi değiştiren adlandırılmış/sözde bir @page kuralı UnsupportedNamedPageException fırlatır. Sayfa boyutunu ve döndürmesini adlandırılmış bir @page kuralı üzerinden değil, Config üzerinden ayarlayın.
Sayfa float’ları bağlantıları akışta tutar. Bir bağlantı ek açıklaması içeren float’lanmış bir kutu, bir HTML_PAGE_FLOAT_* tanılamasıyla normal akışa geri döner; çünkü bağlantı dikdörtgeni akış konumuna bağlıdır.

Performans

Her özellik sınırlı miktarda tek geçişli iş ekler: adlandırılmış dizeler string-set öğesi başına bir değer kaydeder; adlandırılmış sayfalar sayfa başına bir kenar boşluğu kutusu çözümlemesi ekler; çalışan öğeler park edilen öğe başına bir metin arabelleği yakalar; sayfa float’ları sayfa başına bir bant ayırır. Hiçbiri bir belge ağacı tutmaz; böylece akış işleyicisinin O(iç içe geçme derinliği) bellek modeli korunur. Sayfa başına performance_budget (wall_ms: 1500, peak_mb: 64) değişmez.

Güvenlik notları

Bu bayraklar giriş yüzeyini genişletmez. HTML güvenlik politikası, CSS özellik izin listesi ve stil sayfası bayt ile iç içe geçme üst sınırları değişmeden uygulanır. Yakalanan dize ve öğe içeriği, diğer her metinle aynı çıkış yolu üzerinden çıkışlanır. Özellikler yeni bir alım kanalı değil, yerleşim davranışı ekler.

Uygunluk

İfade	Standart	Madde
`string-set` adlandırılmış bir dize kaydeder; `string()` onu bir sayfa kenar boşluğu kutusunda çözümler.	W3C CSS Generated Content for Paged Media	§3
`position: running()` bir öğeyi akıştan çıkarır; `content: element()` onu yeniden oynatır.	W3C CSS Generated Content for Paged Media	§5
`page` özelliği ve `@page <ident>` adlandırılmış bir sayfa bağlamı seçer.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` bir kutuyu blok ekseninde bir sayfa bandına float’lar.	W3C CSS Page Floats Level 3	§5

Bunlar, çalışma grubu modülü özelliklerinin önizleme uygulamalarıdır. NextPDF, yukarıdaki belgelenmiş hata-durumunda-kapalı sınırlarıyla tek geçişli bir alt kümeyi uygular. Özellik başına doğrulanmış durum CSS destek matrisinde izlenir; burada uçtan uca hiçbir uygunluk iddia edilmez. Hiçbir standart metin olduğu gibi aktarılmaz.