độ ổn định: Thử nghiệm

Cờ xem trước CSS paged-media (GCPM running content, named pages, page floats)

Tổng quan nhanh

Bản xem trước opt-in. Bốn tính năng CSS này mặc định tắt. Khi cờ tắt, engine cho ra kết quả byte-identical với một bản build chưa từng biết tính năng này tồn tại. Chỉ bật một tính năng khi bạn thực sự muốn, và hãy kiểm chứng kết quả cho tài liệu của bạn.

Trình kết xuất HTML bổ sung bốn tính năng paged-media opt-in từ các mô-đun CSS Paged Media và Generated Content for Paged Media (GCPM). Mỗi tính năng là một cờ riêng trên CssFeatureFlags. Mỗi tính năng đi kèm một ranh giới fail-closed trung thực: một cấu trúc mà engine single-pass không thể phân giải trung thực sẽ bị bỏ qua hoặc suy giảm kèm một chẩn đoán có tên, không bao giờ kết xuất sai.

Tính năng	Cờ	Nó làm gì khi bật
Named strings (GCPM)	`runningStrings`	Bắt giá trị qua `string-set` cộng với `string()` trong các margin box `@page` — đầu trang và chân trang chạy động.
Named pages (Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, thuộc tính `page:`, và `:first` / `:left` / `:right` / `:blank` — các margin box và trang trí theo từng trang.
Running elements (GCPM)	`runningElements`	`position: running(<ident>)` cộng với `content: element(<ident>)` — phát lại văn bản của một phần tử trong một margin box.
Page floats (Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — di chuyển một box vào dải trên hoặc dưới của trang.

Cài đặt

composer require nextpdf/core:^3

Các cờ này đi kèm gói core. Bề mặt công khai CssFeatureFlags là @since 6.1.0. Phiên bản engine (Version::VERSION) không đổi; các tính năng này có tính bổ sung và mặc định tắt.

Tổng quan khái niệm

Trình kết xuất là single-pass và streaming (xem ADR-001). Nó không giữ cây tài liệu nào và ghi kết quả một lần theo thứ tự tài liệu. Ràng buộc đó định hình mọi tính năng ở đây. Mỗi tính năng phân giải những gì nó thấy được trong một lượt xuôi và fail-closed với bất cứ thứ gì cần một lượt thứ hai hoặc một cây được giữ lại. Ranh giới được ghi tài liệu, không bị giấu — biết một tính năng dừng ở đâu là một phần của việc sử dụng nó.

Bạn bật một tính năng bằng cách dựng CssFeatureFlags với cờ đặt thành true rồi truyền nó vào Config. Khi một cờ tắt, CSS tương ứng được phân tích và bỏ qua hệt như một thuộc tính không hỗ trợ, nên kết quả là byte-identical với một bản build không có tính năng đó.

Chuỗi có tên — `runningStrings`

string-set: <ident> content() ghi lại một giá trị khi engine đi qua phần tử. Một tham chiếu string(<ident>) bên trong một margin box @page khi đó phân giải thành giá trị gần nhất thấy được trên trang đó. Đây là cơ chế tiêu chuẩn cho một đầu trang chạy động bám theo chương hoặc mục hiện hành.

Việc phân giải theo nguyên tắc single-pass “thấy gần nhất trên trang này”. Một tham chiếu string() phân giải thành giá trị cuối cùng mà engine ghi lại trước khi nó dàn trang các margin box của trang đó.

Ranh giới fail-closed. Khi cờ tắt, string() phân giải thành chuỗi rỗng và kết quả vẫn byte-identical. Một danh sách nội dung string-set dị dạng sẽ bỏ một cặp gán đó rồi tiếp tục; nó không bao giờ hủy bỏ quá trình kết xuất.

Trang có tên — `namedPagesAdvanced`

Thuộc tính page: <ident> gán một phần tử vào một ngữ cảnh trang có tên, và một quy tắc @page <ident> khớp cung cấp các margin box và trang trí trang cho ngữ cảnh đó. Các lớp giả của trang :first, :left, :right, và :blank chọn trang đầu tiên, các trang recto và verso, và các trang để trống có chủ ý.

Tính năng này chọn các margin box và trang trí của một trang có tên hay trang giả. Nó không thay đổi hình học của trang.

Ranh giới fail-closed. Một quy tắc @page có tên hay giả cố thay đổi hình học — size, rotate, hoặc một margin của content-box làm đổi kích thước vùng trang — sẽ fail-closed với UnsupportedNamedPageException thay vì âm thầm tạo ra một trang lệch. Kênh khớp lớp giả là lát cắt đầu tiên; các trường hợp selector rộng hơn được hoãn lại và ghi tài liệu.

Phần tử chạy — `runningElements`

position: running(<ident>) gỡ một phần tử khỏi luồng bình thường và đỗ nó dưới một cái tên. content: element(<ident>) trong một margin box khi đó phát lại phần tử đó trên mỗi trang. Hãy dùng nó khi một đầu trang cần toàn bộ văn bản đã định kiểu của một tiêu đề, chứ không chỉ một chuỗi đã bắt.

Ranh giới fail-closed. Lát cắt này chỉ phát lại văn bản của running element mà thôi. Nội dung phong phú — ảnh, các phần tử thay thế, cấu trúc khối lồng nhau — bị bỏ, và engine phát ra một chẩn đoán HTML_RUNNING_ELEMENT_DEGRADED để sự mất mát đó nhìn thấy được, không âm thầm. Một phần tử running() tham chiếu chính nó, một running() lồng nhau, hoặc một lần bắt vượt quá ngân sách nội bộ đều fail-closed. Khi cờ tắt, running() và element() là vô hiệu.

Float trang — `pageFloats`

float: top, float: bottom, và float: snap di chuyển một box vào dải trên hoặc dưới của trang theo trục khối, dành sẵn chiều cao của dải để văn bản xung quanh chảy lại quanh vùng đã dành.

float: bottom (và snap phân giải về dải dưới) là trường hợp mà engine single-pass xử lý trực tiếp: box được bắt và đặt vào dải dưới của trang khi trang đóng lại. float: top suy biến về dải trên cùng của trang.

Ranh giới fail-closed. snap theo trục inline (snap-inline) không được hỗ trợ. Một box mang một tác dụng phụ không di chuyển được — ví dụ một chú thích liên kết, mà hình chữ nhật của nó gắn với vị trí trong luồng — không thể được dời chỗ an toàn, nên nó quay về luồng bình thường và engine phát ra một chẩn đoán HTML_PAGE_FLOAT_* giải thích lần dự phòng đó. Khi cờ tắt, float: top | bottom | snap được coi là một giá trị không hỗ trợ và bị bỏ qua.

Bề mặt API

Ký hiệu	Vị trí	Vai trò
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	Tập cờ opt-in bất biến; hàm dựng nhận `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats` (tất cả mặc định `false`).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	Gắn tập cờ vào một cấu hình tài liệu.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	Phân giải một tập cờ cho một chế độ kết xuất (chế độ Safe ép mọi cờ về tắt; chế độ Normal dùng tập cờ tường minh, hoặc `allEnabled()` khi không cung cấp).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	Được ném ra khi một quy tắc `@page` có tên/giả thay đổi hình học trang.

Các mã cảnh báo chẩn đoán hiện lên qua kênh khuyến nghị của kết quả kết xuất: HTML_RUNNING_ELEMENT_DEGRADED, họ HTML_RUNNING_ELEMENT_*, và họ HTML_PAGE_FLOAT_*.

Mẫu mã — Khởi đầu nhanh

Bật named strings cho một đầu trang chạy động bám theo chương hiện hành.

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

Mẫu mã — Sản phẩm

Bật nhiều cờ cùng lúc, và hãy coi kênh khuyến nghị như một tín hiệu rằng một cấu trúc đã bị suy giảm. Các cờ độc lập với nhau; chỉ bật những cờ bạn dùng.

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

Trường hợp đặc biệt & điểm cần lưu ý

Cả bốn cờ đều độc lập và mặc định tắt. Một cờ tắt cho ra kết quả byte-identical. Chỉ bật những gì bạn dùng.
string() rỗng khi runningStrings tắt, theo thiết kế. Không có cảnh báo cho trường hợp tắt; đó là mặc định đã ghi tài liệu.
Running elements chỉ phát lại văn bản. Ảnh và các khối lồng nhau bên trong một running element bị bỏ kèm HTML_RUNNING_ELEMENT_DEGRADED. Hãy kiểm tra kênh khuyến nghị.
Named pages không thể thay đổi hình học. Một quy tắc @page có tên/giả làm đổi hình học sẽ ném UnsupportedNamedPageException. Hãy đặt kích thước và xoay trang qua Config, không qua một quy tắc @page có tên.
Page floats giữ liên kết trong luồng. Một box đã float chứa một chú thích liên kết sẽ quay về luồng bình thường kèm một chẩn đoán HTML_PAGE_FLOAT_*, vì hình chữ nhật của liên kết gắn với vị trí trong luồng của nó.

Hiệu năng

Mỗi tính năng thêm một lượng công việc single-pass có giới hạn: named strings ghi một giá trị cho mỗi phần tử string-set; named pages thêm một lần phân giải margin-box theo từng trang; running elements bắt một bộ đệm văn bản cho mỗi phần tử đã đỗ; page floats dành một dải cho mỗi trang. Không tính năng nào giữ một cây tài liệu, nên mô hình bộ nhớ O(độ sâu lồng nhau) của trình kết xuất streaming được giữ nguyên. performance_budget theo từng trang (wall_ms: 1500, peak_mb: 64) không đổi.

Ghi chú bảo mật

Các cờ này không mở rộng bề mặt đầu vào. Chính sách bảo mật HTML, danh sách cho phép thuộc tính CSS, cùng các giới hạn về byte stylesheet và độ lồng nhau đều áp dụng không đổi. Nội dung chuỗi và phần tử đã bắt được thoát ký tự qua cùng một đường xuất như mọi văn bản khác. Các tính năng thêm hành vi dàn trang, không phải một kênh nạp dữ liệu mới.

Sự tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản
`string-set` ghi một named string; `string()` phân giải nó trong một margin box của trang.	W3C CSS Generated Content for Paged Media	§3
`position: running()` gỡ một phần tử khỏi luồng; `content: element()` phát lại nó.	W3C CSS Generated Content for Paged Media	§5
Thuộc tính `page` và `@page <ident>` chọn một ngữ cảnh trang có tên.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap` float một box theo trục khối vào một dải trang.	W3C CSS Page Floats Level 3	§5

Đây là các bản triển khai xem trước của các tính năng mô-đun đang trong giai đoạn working-group. NextPDF triển khai một tập con single-pass với các ranh giới fail-closed đã ghi tài liệu ở trên. Trạng thái đã kiểm chứng theo từng thuộc tính được theo dõi trong ma trận hỗ trợ CSS; không có tuyên bố tuân thủ đầu-cuối nào ở đây. Không có văn bản tiêu chuẩn nào được tái tạo.