渲染选项

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	渲染超时上限