レンダリングオプション

RenderOptions クラスは、ChromeがHTMLをPDFにレンダリングする方法を制御するイミュータブルな値オブジェクトです。すべてのセッターは新しいインスタンスを返すため、設定は予測可能で副作用がありません。

オプションの作成

use Yeeefang\TcpdfNext\Artisan\RenderOptions;

// 適切なデフォルト値で開始
$options = RenderOptions::create();

// フルーエントに設定を構築
$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 15, right: 10, bottom: 15, left: 10)
    ->setPrintBackground(true);

オプションの適用

設定した RenderOptions を 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');

ページサイズ

標準フォーマット名を使用して用紙サイズを設定します。

$options = RenderOptions::create()
    ->setPageSize('A4');       // 210 x 297 mm（デフォルト）

対応フォーマット：A0--A6、B0--B6、Letter、Legal、Tabloid、Ledger。

向き

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

マージン

ミリメートル単位で個別のマージンを設定します。

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

ヘッダーまたはフッターテンプレートが有効な場合、上下のマージンはそれらのために確保されるスペースを定義します。

スケール

レンダリングのスケールファクターを制御します。値の範囲は 0.1 から 2.0 で、デフォルトは 1.0（100%）です。

// コンテンツを80%に縮小
$options = RenderOptions::create()
    ->setScale(0.8);

// コンテンツを120%に拡大
$options = RenderOptions::create()
    ->setScale(1.2);

ヘッダーとフッター

Chrome CDPは、ヘッダーとフッター用のHTMLテンプレートをサポートしています。テンプレートにはレンダリング時にChromeが動的な値に置き換える特別なCSSクラスが使用できます。

利用可能なCSSクラス

CSSクラス	置換内容
.date	フォーマットされた印刷日
.title	ドキュメントタイトル
.url	ドキュメントURL
.pageNumber	現在のページ番号
.totalPages	総ページ数

ヘッダーテンプレート

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

フッターテンプレート

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

ヘッダーとフッターの組み合わせ

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

背景の印刷

デフォルトでは、Chromeは背景色と画像を省略します（ブラウザの印刷ダイアログの動作と同じです）。背景のレンダリングを明示的に有効にしてください。

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

CSS @page ルール

有効にすると、HTMLのCSS @page ルールが RenderOptions で設定されたページサイズとマージンを上書きします。

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

HTMLでレイアウトを制御できます：

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

コンテンツの待機

DOMセレクタの待機

特定の要素がDOMに表示されるまでレンダリングを遅延します。JavaScriptが動的にコンテンツを生成する場合に便利です。

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

タイムアウト

ページの読み込みとレンダリングを待つ最大時間（ミリ秒）を設定します。デフォルトは 30000（30秒）です。

$options = RenderOptions::create()
    ->setTimeout(60000);    // 重いページ向けに60秒

タイムアウトを超過すると、TimeoutException がスローされます。

完全な例

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

次のステップ

• HTMLレンダラー -- 文字列、ファイル、URLからのコンテンツの読み込み。
• 高度な機能 -- PDFの結合、CSS注入、スクリーンショット。