渲染選項

RenderOptions 控制 Chrome CDP Page.printToPDF 的所有參數。使用流暢的鏈式 API 進行設定，所有方法皆回傳 static，支援方法串接。

建立選項

use Yeeefang\TcpdfNext\Artisan\RenderOptions;

$options = RenderOptions::create();

頁面設定

頁面尺寸

傳入標準尺寸名稱或自訂寬高（單位：英吋）：

// 標準尺寸
$options->pageSize('A4');       // 210 x 297 mm
$options->pageSize('Letter');   // 8.5 x 11 in
$options->pageSize('Legal');    // 8.5 x 14 in

// 自訂尺寸（英吋）
$options->paperWidth(8.5)->paperHeight(14.0);

方向

$options->portrait();    // 直向（預設）
$options->landscape();   // 橫向

邊界

邊界單位為毫米（mm），個別設定四個方向：

$options->margin(
    top: 20,
    right: 15,
    bottom: 20,
    left: 15,
);

也可以統一設定：

$options->marginAll(20);  // 四邊皆為 20mm

列印選項

背景色彩與圖片

預設情況下，Chrome 不會列印背景色彩與背景圖片。啟用此選項以保留完整的視覺效果：

$options->printBackground();     // 啟用
$options->printBackground(false); // 停用

縮放

設定頁面內容的縮放比例，有效範圍為 0.1 至 2.0：

$options->scale(0.8);  // 縮小至 80%
$options->scale(1.5);  // 放大至 150%

列印媒體模擬

強制 Chrome 使用 @media print 或 @media screen 的樣式規則：

$options->mediaType('print');   // 使用列印媒體樣式（預設）
$options->mediaType('screen');  // 使用螢幕媒體樣式

頁首與頁尾

啟用頁首頁尾

$options->displayHeaderFooter();

自訂模板

模板使用 HTML 語法，Chrome 提供以下佔位符：

佔位符	說明
<span class="date"></span>	格式化的列印日期
<span class="title"></span>	文件標題
<span class="url"></span>	文件的 URL
<span class="pageNumber"></span>	目前頁碼
<span class="totalPages"></span>	總頁數

$options->displayHeaderFooter()
    ->headerTemplate('
        <div style="font-size:9px; width:100%; text-align:center; color:#999;">
            ACME Corp. — 機密文件
        </div>
    ')
    ->footerTemplate('
        <div style="font-size:9px; width:100%; text-align:center; color:#999;">
            第 <span class="pageNumber"></span> 頁，共 <span class="totalPages"></span> 頁
        </div>
    ');

WARNING

頁首頁尾模板中的 font-size 必須明確指定，Chrome 預設使用 0px 字型大小。

等待策略

waitForSelector()

等待指定的 CSS 選擇器出現在 DOM 中後才開始渲染，適用於非同步載入的內容：

$options->waitForSelector('#chart-rendered');

waitForTimeout()

等待固定的毫秒數。建議優先使用 waitForSelector() 以獲得更可靠的結果：

$options->waitForTimeout(2000);  // 等待 2 秒

逾時設定

設定整個渲染流程的最大等待時間（毫秒）。超過此時間會拋出 RenderTimeoutException：

$options->timeout(30_000);  // 30 秒（預設值）
$options->timeout(60_000);  // 複雜頁面可延長至 60 秒

完整範例

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

$options = RenderOptions::create()
    ->pageSize('A4')
    ->landscape()
    ->margin(top: 25, right: 15, bottom: 25, left: 15)
    ->printBackground()
    ->scale(0.9)
    ->displayHeaderFooter()
    ->headerTemplate('<div style="font-size:8px; text-align:center; width:100%;">月度報表</div>')
    ->footerTemplate('<div style="font-size:8px; text-align:right; width:100%; padding-right:15mm;">
        <span class="pageNumber"></span> / <span class="totalPages"></span>
    </div>')
    ->waitForSelector('.data-loaded')
    ->timeout(45_000);

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

方法一覽

方法	預設值	說明
pageSize(string $size)	'A4'	設定標準頁面尺寸
paperWidth(float $inches)	—	自訂紙張寬度（英吋）
paperHeight(float $inches)	—	自訂紙張高度（英吋）
portrait()	預設	設定為直向
landscape()	—	設定為橫向
margin(...)	各邊 10mm	設定頁面邊界（mm）
marginAll(float $mm)	—	統一設定四邊邊界
printBackground(bool)	false	是否列印背景
scale(float $factor)	1.0	頁面縮放比例
mediaType(string $type)	'print'	媒體類型模擬
displayHeaderFooter(bool)	false	是否顯示頁首頁尾
headerTemplate(string)	—	頁首 HTML 模板
footerTemplate(string)	—	頁尾 HTML 模板
waitForSelector(string)	—	等待 DOM 選擇器
waitForTimeout(int $ms)	—	等待固定毫秒數
timeout(int $ms)	30000	渲染逾時上限