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

การจัดวางแบบ retained สำหรับ CSS Grid (grid-template-areas)

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

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

โดยค่าเริ่มต้น ตัวเรนเดอร์เป็นแบบ single-pass และ streaming (ดู ADR-001) CSS Grid ที่ประกาศด้วย grid-template-areas ไม่สามารถวางได้ในการผ่านไปข้างหน้า ครั้งเดียว ดังนั้นเอนจินแบบ streaming จึงส่งคำเตือน HTML_GRID_REQUIRES_RETAINED และถอยกลับไปยัง block flow โหมด retained คือ opt-in ที่แทนที่การถอยกลับนั้นด้วย การจัดวางจริง: Config::withCssLayoutMode(CssLayoutMode::Retained) ส่ง grid แบบ grid-template-areas ที่มีคอลัมน์แน่นอนผ่าน GridLayoutEngine ซึ่งวางองค์ประกอบ ลูกลงใน cell ที่มีชื่อของมัน

การติดตั้ง

composer require nextpdf/core:^3

โหมดการจัดวางมาในแพ็กเกจ core opt-in Config::withCssLayoutMode เป็น @since 6.0.0 ค่าเริ่มต้นยังคงเป็น CssLayoutMode::Streaming

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

CssLayoutMode เป็น enum ที่มีชนิดบน Config Streaming เป็นค่าเริ่มต้นและเป็น พฤติกรรมที่มีมาแต่เดิม; Retained ทำให้เอกสารเลือกใช้ grid engine โหมด retained ถือชุดโหนดที่เก็บไว้ซึ่งมีขอบเขต (retainedNodeBudget ค่าเริ่มต้น 50,000 จำกัด อยู่ในช่วง [5,000, 100,000]) เพื่อให้เอนจินแก้ไข grid ที่ streaming ทำไม่ได้ — โดยไม่ละทิ้งวินัยด้านหน่วยความจำของเอนจิน

เมื่อโหมด retained เปิดและเอนจินพบ grid แบบ grid-template-areas ที่คอลัมน์แน่นอน มันจะจัด grid ออกมาจริง ๆ คอลัมน์ที่แน่นอนคือความยาวคงที่ เปอร์เซ็นต์ หรือหน่วย fr ที่แก้ไขเทียบกับความกว้างของเนื้อหา แถวจะไหลโดยอัตโนมัติ องค์ประกอบลูกจะถูกกำหนด ให้กับ cell ที่ชื่อ area ของมันเลือก

ADR-001 บันทึกอินแวเรียนต์ของ streaming การแก้ไขเพิ่มเติมวันที่ 2026-06-28 ของ ADR-001 เพิ่มข้อยกเว้นแบบ opt-in สำหรับ retained: ค่าเริ่มต้น streaming ไม่ถูกแตะต้องและยังคงเป็นแบบจำลอง single-pass; โหมด retained เป็นข้อยกเว้นแบบ opt-in ที่มีขอบเขตชัดเจนสำหรับกรณี grid

ขอบเขต — สิ่งที่โหมด retained จัดวาง และสิ่งที่ยังถอยกลับ

โหมด retained จัดการกรณี grid-template-areas ที่มีคอลัมน์แน่นอนและกรณีนั้น เท่านั้น ทุกอย่างนอกเหนือจากนั้นยังคงคำเตือน HTML_GRID_REQUIRES_RETAINED และ การถอยกลับไปยัง block แม้เมื่อโหมด retained เปิด:

grid-auto-flow: column และ grid-auto-flow: dense
subgrid
คิวรี @container
track คอลัมน์แบบ auto หรือ intrinsic (auto, min-content, max-content)

เหล่านี้เป็นสไลซ์ที่เลื่อนออกไป ไม่ใช่ช่องว่างที่เงียบ ๆ grid ที่พึ่งพาสิ่งใดสิ่งหนึ่ง ในนี้จะลดทอนไปยัง block flow และบอกคุณเช่นนั้น

ขอบเขต fail-closed ความไม่ตรงกันของความกว้างระหว่าง capture กับ engine — ความกว้างของเนื้อหาที่วัดได้ไม่ตรงกับความกว้างที่ grid engine แก้ไขเทียบกับ — จะ fail closed แทนที่จะสร้าง grid ที่วางผิดที่ โหมด retained ยังเข้ากันไม่ได้กับโหมด การเรนเดอร์ CSS แบบ Safe: CssRenderingMode::Safe รวมกับ CssLayoutMode::Retained จะยก IncompatibleRenderingModeException ในการตรวจสอบความถูกต้องของ config CssLayoutMode::Auto ถูกสงวนไว้และยก NotImplementedException

พื้นผิวของ API

สัญลักษณ์	ตำแหน่ง	บทบาท
`Config::withCssLayoutMode(CssLayoutMode $mode): self`	`src/Core/Config.php`	ให้เอกสารเลือกใช้การจัดวางแบบ `Streaming` (ค่าเริ่มต้น) หรือ `Retained`
`Config::withRetainedNodeBudget(int $budget): self`	`src/Core/Config.php`	กำหนดขอบเขตชุดโหนดที่เก็บไว้ (`[5,000, 100,000]`, ค่าเริ่มต้น `50,000`)
`Config::isRetainedMode(): bool`	`src/Core/Config.php`	รายงานว่าเอกสารอยู่ในโหมด retained หรือไม่
`CssLayoutMode`	`src/Core/`	`Streaming`, `Retained`; `Auto` ถูกสงวนไว้ (`NotImplementedException`)
`GridLayoutEngine`	`src/Html/`	เอนจินการวาง grid แบบ retained
`IncompatibleRenderingModeException`	`src/Exception/`	ถูกโยนเมื่อโหมด CSS แบบ Safe ถูกรวมกับโหมด retained

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

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

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

ตรวจจับกรณีโหมดที่เข้ากันไม่ได้ในเวลากำหนดค่า และอ่านโหมดที่ใช้งานอยู่กลับมา เพื่อให้เส้นทางชัดเจน

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

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

Streaming ยังคงเป็นค่าเริ่มต้นและเหมือนกันทุกไบต์ โหมด retained เปลี่ยน เอาต์พุตเฉพาะเอกสารที่คุณเลือกใช้
เฉพาะ grid-template-areas ที่มีคอลัมน์แน่นอนเท่านั้น column auto-flow, การแพ็คแบบ dense, subgrid, @container และคอลัมน์ intrinsic ยังคงคำเตือน HTML_GRID_REQUIRES_RETAINED และการถอยกลับไปยัง block
โหมด Safe เป็นแบบไม่รวมกัน CssRenderingMode::Safe บวกกับ CssLayoutMode::Retained จะโยน IncompatibleRenderingModeException
Auto ถูกสงวนไว้ CssLayoutMode::Auto ยก NotImplementedException; มันยังไม่ใช่ตัวเลือกที่สามที่ใช้งานได้
ความกว้างไม่ตรงกันจะ fail closed ความไม่ตรงกันของความกว้างเนื้อหา ระหว่าง capture กับ engine จะถูกปฏิเสธ ไม่ใช่เรนเดอร์ผิด

ประสิทธิภาพ

โหมด retained ถือชุดโหนดที่มีขอบเขตแทนที่จะเป็น document tree เต็มรูปแบบ; retainedNodeBudget (ค่าเริ่มต้น 50,000) จำกัดมัน การวาง grid เป็นเชิงเส้นตาม จำนวนโหนดและ cell performance_budget ต่อหน้า (wall_ms: 1500, peak_mb: 64) ใช้บังคับ; grid ขนาดใหญ่ควรคำนึงถึงงบประมาณเมื่อยกขอบเขตโหนดขึ้นไปสู่เพดาน 100,000

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

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

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

ข้อความ	มาตรฐาน	ข้อ
`grid-template-areas` ตั้งชื่อ cell ของ grid; area ที่มีชื่อวางไอเทม	W3C CSS Grid Layout Module Level 1	§7.3
track แบบคงที่ เปอร์เซ็นต์ และ `fr` ที่ระบุชัดเจนกำหนดขนาดเทียบกับความกว้างของเนื้อหา	W3C CSS Grid Layout Module Level 1	§7.2

นี่คือการนำชุดย่อยของ grid-template-areas ที่มีคอลัมน์แน่นอนมาใช้แบบ preview สถานะที่ตรวจสอบแล้วต่อพร็อพเพอร์ตีถูกติดตามใน CSS support matrix; ไม่มีการอ้างความสอดคล้องแบบ end-to-end ในที่นี้ ไม่มีการคัดลอกข้อความมาตรฐานซ้ำ