ความเสถียร: ทดลอง

แฟล็ก preview ของ CSS แบบ paged-media (เนื้อหาแบบ running ของ GCPM, named pages, page floats)

ภาพรวมโดยย่อ

Preview แบบ opt-in คุณสมบัติ CSS ทั้งสี่อย่างนี้เปิดเป็นค่าเริ่มต้นปิด เมื่อ แฟล็กปิด เอนจินจะสร้างเอาต์พุตที่เหมือนกันทุกไบต์กับบิลด์ที่ไม่เคยรู้จัก คุณสมบัตินี้มาก่อน เปิดคุณสมบัติใดก็ต่อเมื่อคุณต้องการใช้มัน และตรวจสอบ ผลลัพธ์สำหรับเอกสารของคุณ

ตัวเรนเดอร์ HTML เพิ่มคุณสมบัติ paged-media แบบ opt-in สี่อย่างจากโมดูล CSS Paged Media และ Generated Content for Paged Media (GCPM) แต่ละอย่างเป็นแฟล็กแยกกันบน CssFeatureFlags แต่ละอย่างมีขอบเขต fail-closed ที่ตรงไปตรงมา: โครงสร้างที่เอนจิน แบบ single-pass ไม่สามารถแก้ไขได้อย่างซื่อตรงจะถูกตัดทิ้งหรือลดทอนพร้อมไดแอกโนสติก ที่มีชื่อกำกับ ไม่มีการเรนเดอร์ผิดเด็ดขาด

คุณสมบัติ	แฟล็ก	สิ่งที่ทำเมื่อเปิด
Named strings (GCPM)	`runningStrings`	การจับค่า `string-set` พร้อม `string()` ใน margin box ของ `@page` — ส่วนหัวและส่วนท้ายแบบ running
Named pages (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, พร็อพเพอร์ตี `page:` และ `:first` / `:left` / `:right` / `:blank` — margin box และการตกแต่งต่อหน้า
Running elements (GCPM)	`runningElements`	`position: running(<ident>)` พร้อม `content: element(<ident>)` — เล่นซ้ำข้อความขององค์ประกอบใน margin box
Page floats (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — ย้ายกล่องเข้าไปยังแถบบนหรือล่างของหน้า

การติดตั้ง

composer require nextpdf/core:^3

แฟล็กมาในแพ็กเกจ core พื้นผิวสาธารณะ CssFeatureFlags เป็น @since 6.1.0 เวอร์ชัน ของเอนจิน (Version::VERSION) ไม่เปลี่ยนแปลง; คุณสมบัติเหล่านี้เป็นแบบเสริมและเปิด เป็นค่าเริ่มต้นปิด

ภาพรวมเชิงแนวคิด

ตัวเรนเดอร์เป็นแบบ single-pass และ streaming (ดู ADR-001) มันไม่เก็บ document tree ใด ๆ และเขียนเอาต์พุตเพียงครั้งเดียวตามลำดับเอกสาร ข้อจำกัด นั้นกำหนดรูปแบบของทุกคุณสมบัติในที่นี้ แต่ละคุณสมบัติแก้ไขสิ่งที่มองเห็นได้ในการผ่าน ไปข้างหน้าครั้งเดียว และจะ fail closed กับสิ่งใดก็ตามที่ต้องการการผ่านครั้งที่สองหรือ tree ที่เก็บไว้ ขอบเขตนี้ถูกบันทึกไว้ ไม่ใช่ซ่อนไว้ — การรู้ว่าคุณสมบัติหยุดตรงไหนเป็น ส่วนหนึ่งของการใช้งานมัน

คุณเปิดใช้งานคุณสมบัติด้วยการสร้าง CssFeatureFlags โดยตั้งแฟล็กเป็น true และส่ง มันให้ Config เมื่อแฟล็กปิด CSS ที่เกี่ยวข้องจะถูกแยกวิเคราะห์และละเว้นเหมือนกับพร็อพ เพอร์ตีที่ไม่รองรับทุกประการ ดังนั้นเอาต์พุตจึงเหมือนกันทุกไบต์กับบิลด์ที่ไม่มีคุณสมบัตินี้

Named strings — `runningStrings`

string-set: <ident> content() บันทึกค่าขณะที่เอนจินผ่านองค์ประกอบนั้น จากนั้นการ อ้างอิง string(<ident>) ภายใน margin box ของ @page จะแก้ไขเป็นค่าล่าสุดที่พบบน หน้านั้น นี่คือกลไกมาตรฐานสำหรับส่วนหัวแบบ running ที่ติดตามบทหรือส่วนปัจจุบัน

การแก้ไขเป็นแบบ single-pass “ที่เห็นล่าสุดบนหน้านี้” การอ้างอิง string() จะแก้ไขเป็น ค่าสุดท้ายที่เอนจินบันทึกไว้ก่อนจะจัด margin box ของหน้านั้น

ขอบเขต fail-closed เมื่อแฟล็กปิด string() จะแก้ไขเป็นสตริงว่าง และเอาต์พุตยังคง เหมือนกันทุกไบต์ รายการเนื้อหา string-set ที่ผิดรูปแบบจะตัดคู่การกำหนดค่านั้นออกหนึ่ง คู่แล้วทำงานต่อ; มันไม่เคยยกเลิกการเรนเดอร์

Named pages — `namedPagesAdvanced`

พร็อพเพอร์ตี page: <ident> กำหนดองค์ประกอบให้กับบริบทหน้าที่มีชื่อ และกฎ @page <ident> ที่ตรงกันจะจัดหา margin box และการตกแต่งหน้าของบริบทนั้น Pseudo-class ของหน้า :first, :left, :right และ :blank เลือกหน้าแรก หน้า recto และ verso และหน้าที่ตั้งใจให้ว่าง

คุณสมบัตินี้เลือก margin box และการตกแต่ง ของหน้าที่มีชื่อหรือ pseudo มันไม่ เปลี่ยน เรขาคณิต (geometry) ของหน้า

ขอบเขต fail-closed กฎ @page ที่มีชื่อหรือ pseudo ซึ่งพยายามเปลี่ยนเรขาคณิต — size, rotate หรือ margin ของ content-box ที่ปรับขนาดพื้นที่หน้า — จะ fail closed ด้วย UnsupportedNamedPageException แทนที่จะสร้างหน้าที่เยื้องอย่างเงียบ ๆ ช่องทาง การจับคู่ pseudo-class เป็นสไลซ์แรก; กรณี selector ที่กว้างกว่าถูกเลื่อนออกไปและบันทึกไว้

Running elements — `runningElements`

position: running(<ident>) นำองค์ประกอบออกจาก flow ปกติและจอดมันไว้ภายใต้ชื่อหนึ่ง content: element(<ident>) ใน margin box จะเล่นซ้ำองค์ประกอบนั้นในแต่ละหน้า ใช้มัน เมื่อส่วนหัวต้องการข้อความที่จัดสไตล์เต็มรูปแบบของหัวเรื่อง ไม่ใช่เพียงสตริงที่จับมา

ขอบเขต fail-closed สไลซ์นี้เล่นซ้ำเฉพาะ ข้อความ ของ running element เท่านั้น เนื้อหาที่หลากหลาย — ภาพ องค์ประกอบที่ถูกแทนที่ โครงสร้างบล็อกที่ซ้อนกัน — จะถูกตัด ทิ้ง และเอนจินจะส่งไดแอกโนสติก HTML_RUNNING_ELEMENT_DEGRADED เพื่อให้การสูญหายมอง เห็นได้ ไม่ใช่เงียบ ๆ องค์ประกอบ running() ที่อ้างอิงตัวเอง, running() ที่ซ้อนกัน หรือ การจับที่เกินงบประมาณภายในจะ fail closed เมื่อแฟล็กปิด running() และ element() จะไม่ทำงาน

Page floats — `pageFloats`

float: top, float: bottom และ float: snap ย้ายกล่องเข้าไปยังแถบบนหรือล่างของ หน้าในแกนบล็อก โดยจองความสูงของแถบไว้เพื่อให้ข้อความรอบ ๆ ไหลเลี่ยงรอบบริเวณที่จองไว้

float: bottom (และ snap ที่แก้ไขไปยังแถบล่าง) คือกรณีที่เอนจินแบบ single-pass จัด การได้โดยตรง: กล่องจะถูกจับและวางไว้ในแถบล่างของหน้าขณะที่หน้าปิด float: top ลดรูปลง เป็นแถบบนสุดของหน้า

ขอบเขต fail-closed snap ในแกน inline (snap-inline) ไม่รองรับ กล่องที่มีผลข้าง เคียงซึ่งย้ายไม่ได้ — ตัวอย่างเช่น link annotation ที่สี่เหลี่ยมผูกอยู่กับตำแหน่ง flow ของ มัน — ไม่สามารถย้ายตำแหน่งได้อย่างปลอดภัย ดังนั้นมันจึงถอยกลับไปยัง flow ปกติและ เอนจินจะส่งไดแอกโนสติก HTML_PAGE_FLOAT_* อธิบายการถอยกลับ เมื่อแฟล็กปิด float: top | bottom | snap จะถูกถือว่าเป็นค่าที่ไม่รองรับและถูกละเว้น

พื้นผิวของ API

สัญลักษณ์	ตำแหน่ง	บทบาท
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	ชุดแฟล็ก opt-in ที่เปลี่ยนแปลงไม่ได้; ตัวสร้างรับ `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` (ค่าเริ่มต้น `false` ทั้งหมด)
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	แนบชุดแฟล็กเข้ากับการกำหนดค่าเอกสาร
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	แก้ไขชุดแฟล็กสำหรับโหมดการเรนเดอร์ (โหมด Safe บังคับให้ทุกแฟล็กปิด; โหมด Normal ใช้ชุดที่ระบุอย่างชัดเจน หรือ `allEnabled()` เมื่อไม่ได้จัดหามาให้)
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	ถูกโยนเมื่อกฎ `@page` ที่มีชื่อ/pseudo เปลี่ยนเรขาคณิตของหน้า

รหัสคำเตือนไดแอกโนสติกปรากฏผ่านช่องทางคำแนะนำของผลการเรนเดอร์: HTML_RUNNING_ELEMENT_DEGRADED, ตระกูล HTML_RUNNING_ELEMENT_* และตระกูล HTML_PAGE_FLOAT_*

ตัวอย่างโค้ด — เริ่มต้นอย่างรวดเร็ว

เปิดใช้ named strings สำหรับส่วนหัวแบบ running ที่ติดตามบทปัจจุบัน

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

ตัวอย่างโค้ด — สำหรับใช้งานจริง

เปิดหลายแฟล็กพร้อมกัน และถือว่าช่องทางคำแนะนำเป็นสัญญาณว่าโครงสร้างถูกลดทอน แฟล็กเป็นอิสระต่อกัน; เปิดเฉพาะที่คุณใช้

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

กรณีขอบและข้อควรระวัง

แฟล็กทั้งสี่เป็นอิสระต่อกันและเปิดเป็นค่าเริ่มต้นปิด แฟล็กที่ปิดให้เอาต์พุต ที่เหมือนกันทุกไบต์ เปิดเฉพาะสิ่งที่คุณใช้
string() เป็นค่าว่างเมื่อ runningStrings ปิด ตามที่ออกแบบไว้ ไม่มีคำเตือน สำหรับกรณีปิด; มันเป็นค่าเริ่มต้นที่บันทึกไว้
Running elements เล่นซ้ำเฉพาะข้อความ ภาพและบล็อกที่ซ้อนกันภายใน running element จะถูกตัดทิ้งพร้อม HTML_RUNNING_ELEMENT_DEGRADED ตรวจสอบช่องทาง คำแนะนำ
Named pages ไม่สามารถเปลี่ยนเรขาคณิตได้ กฎ @page ที่มีชื่อ/pseudo ซึ่ง เปลี่ยนเรขาคณิตจะโยน UnsupportedNamedPageException ตั้งขนาดหน้าและการ หมุนผ่าน Config ไม่ใช่ผ่านกฎ @page ที่มีชื่อ
Page floats คงลิงก์ไว้ใน flow กล่องที่ลอยซึ่งมี link annotation จะถอยกลับ ไปยัง flow ปกติพร้อมไดแอกโนสติก HTML_PAGE_FLOAT_* เพราะสี่เหลี่ยมของลิงก์ ผูกอยู่กับตำแหน่ง flow ของมัน

ประสิทธิภาพ

แต่ละคุณสมบัติเพิ่มงานแบบ single-pass ในปริมาณที่มีขอบเขต: named strings บันทึก หนึ่งค่าต่อองค์ประกอบ string-set; named pages เพิ่มการแก้ไข margin box ต่อหน้า; running elements จับบัฟเฟอร์ข้อความหนึ่งรายการต่อองค์ประกอบที่จอดไว้; page floats จองหนึ่งแถบต่อหน้า ไม่มีคุณสมบัติใดเก็บ document tree ดังนั้นแบบจำลองหน่วยความจำ O(ความลึกของการซ้อน) ของตัวเรนเดอร์แบบ streaming จึงยังคงอยู่ performance_budget ต่อหน้า (wall_ms: 1500, peak_mb: 64) ไม่เปลี่ยนแปลง

หมายเหตุด้านความปลอดภัย

แฟล็กเหล่านี้ไม่ขยายพื้นผิวอินพุต นโยบายความปลอดภัย HTML, allowlist ของพร็อพเพอร์ตี CSS และขีดจำกัดของไบต์สไตล์ชีตและการซ้อนใช้บังคับเหมือนเดิม เนื้อหาสตริงและองค์ ประกอบที่จับมาจะถูก escape ผ่านเส้นทางเอาต์พุตเดียวกันกับข้อความอื่นใด คุณสมบัติเพิ่ม พฤติกรรมการจัดวาง ไม่ใช่ช่องทางการรับเข้าใหม่

ความสอดคล้อง

ข้อความ	มาตรฐาน	ข้อ
`string-set` บันทึก named string; `string()` แก้ไขมันใน margin box ของหน้า	W3C CSS Generated Content for Paged Media	§3
`position: running()` นำองค์ประกอบออกจาก flow; `content: element()` เล่นซ้ำมัน	W3C CSS Generated Content for Paged Media	§5
พร็อพเพอร์ตี `page` และ `@page <ident>` เลือกบริบทหน้าที่มีชื่อ	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` ลอยกล่องในแกนบล็อกไปยังแถบของหน้า	W3C CSS Page Floats Level 3	§5

เหล่านี้เป็นการนำคุณสมบัติของโมดูล working-group มาใช้แบบ preview NextPDF นำชุดย่อย แบบ single-pass มาใช้พร้อมขอบเขต fail-closed ที่บันทึกไว้ข้างต้น สถานะที่ตรวจสอบแล้ว ต่อพร็อพเพอร์ตีถูกติดตามใน CSS support matrix; ไม่มี การอ้างความสอดคล้องแบบ end-to-end ในที่นี้ ไม่มีการคัดลอกข้อความมาตรฐานซ้ำ