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

Dàn trang chế độ retained cho CSS Grid (grid-template-areas)

Tổng quan nhanh

Bản xem trước opt-in. Chế độ retained mặc định tắt. Chế độ Streaming mặc định cho ra kết quả byte-identical với một bản build chưa từng biết chế độ này tồn tại. Chỉ bật nó cho những tài liệu cần một lưới grid thật, và hãy kiểm chứng kết quả.

Theo mặc định, trình kết xuất là single-pass và streaming (xem ADR-001). Một lưới CSS Grid khai báo bằng grid-template-areas không thể đặt trong một lượt xuôi, nên engine streaming phát ra một cảnh báo HTML_GRID_REQUIRES_RETAINED và quay về luồng khối. Chế độ retained là tùy chọn opt-in thay lần dự phòng đó bằng một bản dàn trang thật: Config::withCssLayoutMode(CssLayoutMode::Retained) định tuyến một lưới grid-template-areas có cột xác định qua GridLayoutEngine, vốn đặt các phần tử con vào các ô có tên của chúng.

Cài đặt

composer require nextpdf/core:^3

Chế độ dàn trang đi kèm gói core. Tùy chọn opt-in Config::withCssLayoutMode là @since 6.0.0. Mặc định vẫn là CssLayoutMode::Streaming.

Tổng quan khái niệm

CssLayoutMode là một enum có kiểu trên Config. Streaming là mặc định và là hành vi lịch sử; Retained chọn một tài liệu vào engine grid. Chế độ retained giữ một tập node retained có giới hạn (retainedNodeBudget, mặc định 50,000, được kẹp trong [5,000, 100,000]) để engine có thể phân giải một lưới mà streaming không làm được — mà không từ bỏ kỷ luật bộ nhớ của engine.

Khi chế độ retained bật và engine gặp một lưới grid-template-areas có các cột xác định, nó dàn lưới đó ra thật. Cột xác định là các độ dài cố định, phần trăm, hoặc đơn vị fr được phân giải dựa trên chiều rộng nội dung. Các hàng chảy tự động. Các phần tử con được gán vào các ô mà tên area của chúng chọn.

ADR-001 ghi lại bất biến streaming. Bản sửa đổi ngày 2026-06-28 cho ADR-001 bổ sung một ngoại lệ opt-in retained: mặc định streaming không bị động đến và vẫn giữ mô hình single-pass; chế độ retained là một ngoại lệ opt-in có giới hạn rõ ràng cho trường hợp grid.

Ranh giới — chế độ retained dàn gì, và cái gì vẫn dự phòng

Chế độ retained xử lý trường hợp grid-template-areas có cột xác định và chỉ trường hợp đó. Mọi thứ ngoài nó vẫn giữ cảnh báo HTML_GRID_REQUIRES_RETAINED và lần dự phòng khối, kể cả khi chế độ retained đang bật:

grid-auto-flow: column và grid-auto-flow: dense.
subgrid.
truy vấn @container.
Các track cột tự động hoặc nội tại (auto, min-content, max-content).

Đây là các lát cắt được hoãn lại, không phải khoảng trống âm thầm. Một lưới phụ thuộc vào một trong số đó sẽ suy giảm về luồng khối và báo cho bạn biết điều đó.

Ranh giới fail-closed. Một sự không khớp chiều rộng giữa lần bắt và engine — chiều rộng nội dung đo được khác với chiều rộng mà engine grid phân giải dựa vào — sẽ fail-closed thay vì tạo ra một lưới đặt sai chỗ. Chế độ retained cũng không tương thích với chế độ kết xuất CSS Safe: CssRenderingMode::Safe kết hợp với CssLayoutMode::Retained làm phát sinh IncompatibleRenderingModeException tại lúc kiểm tra cấu hình. CssLayoutMode::Auto được dành riêng và làm phát sinh NotImplementedException.

Bề mặt API

Ký hiệu	Vị trí	Vai trò
`Config::withCssLayoutMode(CssLayoutMode $mode): self`	`src/Core/Config.php`	Chọn một tài liệu vào dàn trang `Streaming` (mặc định) hoặc `Retained`.
`Config::withRetainedNodeBudget(int $budget): self`	`src/Core/Config.php`	Giới hạn tập node retained (`[5,000, 100,000]`, mặc định `50,000`).
`Config::isRetainedMode(): bool`	`src/Core/Config.php`	Báo cáo tài liệu có đang ở chế độ retained hay không.
`CssLayoutMode`	`src/Core/`	`Streaming`, `Retained`; `Auto` được dành riêng (`NotImplementedException`).
`GridLayoutEngine`	`src/Html/`	Engine đặt lưới grid retained.
`IncompatibleRenderingModeException`	`src/Exception/`	Được ném ra khi chế độ CSS Safe kết hợp với chế độ retained.

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

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\CssLayoutMode;
use NextPDF\Core\Document;

$config = (new Config())->withCssLayoutMode(CssLayoutMode::Retained);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<style>'
    . '.dashboard { display: grid; grid-template-columns: 1fr 2fr;'
    . '  grid-template-areas: "sidebar main"; }'
    . '.sidebar { grid-area: sidebar; } .main { grid-area: main; }'
    . '</style>'
    . '<div class="dashboard">'
    . '  <div class="sidebar">Navigation</div>'
    . '  <div class="main">Report content…</div>'
    . '</div>',
);
$doc->save(__DIR__ . '/grid.pdf');

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

Phát hiện trường hợp chế độ-không-tương-thích tại lúc cấu hình, và đọc lại chế độ đang hoạt động để đường đi tường minh.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Config;
use NextPDF\Core\CssLayoutMode;
use NextPDF\Core\Document;
use NextPDF\Exception\IncompatibleRenderingModeException;

try {
    $config = (new Config())
        ->withCssLayoutMode(CssLayoutMode::Retained)
        ->withRetainedNodeBudget(75_000);
    $config->validate();
} catch (IncompatibleRenderingModeException $e) {
    // Safe CSS mode and retained mode cannot combine. Choose one.
    throw $e;
}

$doc = Document::createStandalone($config);
assert($config->isRetainedMode());

$doc->addPage();
$doc->writeHtml($gridHtml);
$doc->save($out);

// A grid that needs a deferred feature (column auto-flow, subgrid, @container,
// or intrinsic columns) still emits HTML_GRID_REQUIRES_RETAINED and falls back
// to block flow. Inspect the advisory channel.

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

Streaming vẫn là mặc định và byte-identical. Chế độ retained chỉ thay đổi kết quả cho tài liệu mà bạn chọn vào.
Chỉ grid-template-areas có cột xác định. Cột auto-flow, gói dày đặc, subgrid, @container, và cột nội tại vẫn giữ cảnh báo HTML_GRID_REQUIRES_RETAINED và lần dự phòng khối.
Chế độ Safe loại trừ lẫn nhau. CssRenderingMode::Safe cộng với CssLayoutMode::Retained ném IncompatibleRenderingModeException.
Auto được dành riêng. CssLayoutMode::Auto làm phát sinh NotImplementedException; nó chưa phải một lựa chọn thứ ba dùng được.
Không khớp chiều rộng thì fail-closed. Một sự bất đồng về chiều rộng nội dung giữa lần bắt và engine bị từ chối, không kết xuất sai.

Hiệu năng

Chế độ retained giữ một tập node có giới hạn thay vì cả một cây tài liệu; retainedNodeBudget (mặc định 50,000) chặn nó lại. Việc đặt lưới có độ phức tạp tuyến tính theo số node và số ô. performance_budget theo từng trang (wall_ms: 1500, peak_mb: 64) áp dụng; với các lưới lớn nên cân nhắc ngân sách này khi nâng ngân sách node về phía trần 100,000.

Ghi chú bảo mật

Chế độ retained 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, và các giới hạn của bộ phân tích đều áp dụng không đổi. Bản thân ngân sách node retained là một giới hạn chống cạn kiệt tài nguyên: nó chặn lượng cấu trúc mà engine sẽ giữ cho một tài liệu đơn lẻ.

Sự tuân thủ

Tuyên bố	Tiêu chuẩn	Điều khoản
`grid-template-areas` đặt tên cho các ô lưới; các area có tên đặt các phần tử.	W3C CSS Grid Layout Module Level 1	§7.3
Các track `fr`, cố định, và phần trăm tường minh định kích thước dựa trên chiều rộng nội dung.	W3C CSS Grid Layout Module Level 1	§7.2

Đây là một bản triển khai xem trước của một tập con grid-template-areas có cột xác định. 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.