Render Option

Class RenderOptions là value object bất biến kiểm soát cách Chrome render HTML sang PDF. Mọi setter trả về instance mới, giữ cấu hình ổn định và không có side-effect.

Tạo Option

use Yeeefang\TcpdfNext\Artisan\RenderOptions;

// Bắt đầu với mặc định hợp lý
$options = RenderOptions::create();

// Xây dựng cấu hình fluent
$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 15, right: 10, bottom: 15, left: 10)
    ->setPrintBackground(true);

Áp dụng Option

Truyền RenderOptions đã cấu hình cho HtmlRenderer::withOptions().

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

HtmlRenderer::create()
    ->loadHtml('<h1>Configured Output</h1>')
    ->withOptions($options)
    ->save('/output/configured.pdf');

Kích thước trang

Đặt định dạng giấy dùng tên định dạng chuẩn.

$options = RenderOptions::create()
    ->setPageSize('A4');       // 210 x 297 mm (mặc định)

Định dạng hỗ trợ: A0--A6, B0--B6, Letter, Legal, Tabloid, Ledger.

Hướng trang

$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setLandscape(true);      // 297 x 210 mm

Margin

Đặt margin riêng lẻ tính bằng millimeter.

$options = RenderOptions::create()
    ->setMargins(
        top: 20,
        right: 15,
        bottom: 20,
        left: 15,
    );

Khi template header hoặc footer được bật, margin trên và dưới định nghĩa khoảng trống dành cho chúng.

Scale

Kiểm soát hệ số scale render. Giá trị từ 0.1 đến 2.0, mặc định 1.0 (100%).

// Thu nhỏ nội dung xuống 80%
$options = RenderOptions::create()
    ->setScale(0.8);

// Phóng to nội dung lên 120%
$options = RenderOptions::create()
    ->setScale(1.2);

Header và Footer

Chrome CDP hỗ trợ template HTML cho header và footer. Template có quyền truy cập class CSS đặc biệt mà Chrome thay thế bằng giá trị động tại thời điểm render.

Class CSS có sẵn

Class CSS	Thay thế bằng
.date	Ngày in đã format
.title	Tiêu đề document
.url	URL document
.pageNumber	Số trang hiện tại
.totalPages	Tổng số trang

Template Header

$options = RenderOptions::create()
    ->setDisplayHeaderFooter(true)
    ->setMargins(top: 25, right: 10, bottom: 20, left: 10)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; padding: 0 10mm; display: flex; justify-content: space-between;">
            <span>Acme Corp -- Confidential</span>
            <span class="date"></span>
        </div>
    ');

Template Footer

$options = RenderOptions::create()
    ->setDisplayHeaderFooter(true)
    ->setMargins(top: 15, right: 10, bottom: 25, left: 10)
    ->setFooterTemplate('
        <div style="font-size: 9px; width: 100%; text-align: center; color: #999;">
            Page <span class="pageNumber"></span> of <span class="totalPages"></span>
        </div>
    ');

Kết hợp Header và Footer

$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 25, right: 15, bottom: 25, left: 15)
    ->setDisplayHeaderFooter(true)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; padding: 0 15mm; display: flex; justify-content: space-between; border-bottom: 1px solid #e0e0e0; padding-bottom: 5px;">
            <span style="font-weight: bold;">Quarterly Report</span>
            <span class="date"></span>
        </div>
    ')
    ->setFooterTemplate('
        <div style="font-size: 8px; width: 100%; padding: 0 15mm; display: flex; justify-content: space-between; color: #888;">
            <span>Acme Corporation</span>
            <span>Page <span class="pageNumber"></span> / <span class="totalPages"></span></span>
        </div>
    ');

In nền

Mặc định, Chrome bỏ qua màu nền và hình ảnh (giống hành vi hộp thoại in trình duyệt). Bật render nền rõ ràng.

$options = RenderOptions::create()
    ->setPrintBackground(true);

CSS Rule @page

Khi bật, CSS rule @page trong HTML ghi đè kích thước trang và margin đã cấu hình trong RenderOptions.

$options = RenderOptions::create()
    ->setPreferCssPageSize(true);

HTML có thể kiểm soát layout:

@page {
    size: A3 landscape;
    margin: 10mm;
}

Chờ nội dung

Chờ DOM Selector

Trì hoãn render cho đến khi phần tử cụ thể xuất hiện trong DOM. Hữu ích khi JavaScript tạo nội dung động.

$options = RenderOptions::create()
    ->setWaitForSelector('#chart-rendered');

Timeout

Đặt thời gian tối đa (millisecond) chờ tải trang và render. Mặc định 30000 (30 giây).

$options = RenderOptions::create()
    ->setTimeout(60000);    // 60 giây cho trang nặng

Nếu timeout bị vượt, TimeoutException được throw.

Ví dụ đầy đủ

use Yeeefang\TcpdfNext\Artisan\HtmlRenderer;
use Yeeefang\TcpdfNext\Artisan\RenderOptions;

$options = RenderOptions::create()
    ->setPageSize('Letter')
    ->setLandscape(false)
    ->setMargins(top: 25, right: 15, bottom: 25, left: 15)
    ->setScale(1.0)
    ->setPrintBackground(true)
    ->setDisplayHeaderFooter(true)
    ->setHeaderTemplate('
        <div style="font-size: 9px; width: 100%; text-align: center;">
            Internal Document -- Do Not Distribute
        </div>
    ')
    ->setFooterTemplate('
        <div style="font-size: 8px; width: 100%; text-align: center; color: #999;">
            <span class="pageNumber"></span> / <span class="totalPages"></span>
        </div>
    ')
    ->setWaitForSelector('.content-ready')
    ->setTimeout(45000);

HtmlRenderer::create()
    ->loadUrl('https://dashboard.example.com/export')
    ->withOptions($options)
    ->save('/exports/dashboard.pdf');

Bước tiếp theo

• HTML Renderer -- Tải nội dung từ chuỗi, file và URL.
• Tính năng nâng cao -- Ghép PDF, chèn CSS, chụp ảnh màn hình.