Render Options

A classe RenderOptions é um value object imutável que controla como o Chrome renderiza seu HTML para PDF. Cada setter retorna uma nova instância, mantendo sua configuração previsível e livre de efeitos colaterais.

Criando Options

use Yeeefang\TcpdfNext\Artisan\RenderOptions;

// Start with sensible defaults
$options = RenderOptions::create();

// Build up configuration fluently
$options = RenderOptions::create()
    ->setPageSize('A4')
    ->setMargins(top: 15, right: 10, bottom: 15, left: 10)
    ->setPrintBackground(true);

Aplicando Options

Passe o RenderOptions configurado para 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');

Tamanho de Página

Defina o formato de papel usando nomes de formato padrão.

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

Formatos suportados: A0--A6, B0--B6, Letter, Legal, Tabloid, Ledger.

Orientação

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

Margens

Defina margens individuais em milímetros.

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

Quando templates de cabeçalho ou rodapé estão habilitados, as margens superior e inferior definem o espaço reservado para eles.

Escala

Controle o fator de escala de renderização. Valores variam de 0.1 a 2.0, com 1.0 como padrão (100%).

// Shrink content to 80%
$options = RenderOptions::create()
    ->setScale(0.8);

// Enlarge content to 120%
$options = RenderOptions::create()
    ->setScale(1.2);

Cabeçalhos e Rodapés

O Chrome CDP suporta templates HTML para cabeçalhos e rodapés. Os templates têm acesso a classes CSS especiais que o Chrome substitui por valores dinâmicos no momento da renderização.

Classes CSS Disponíveis

Classe CSS	Substituída Por
.date	Data de impressão formatada
.title	Título do documento
.url	URL do documento
.pageNumber	Número da página atual
.totalPages	Número total de páginas

Template de Cabeçalho

$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 de Rodapé

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

Cabeçalho e Rodapé Combinados

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

Impressão de Fundo

Por padrão, o Chrome omite cores e imagens de fundo (correspondendo ao comportamento do diálogo de impressão do navegador). Habilite a renderização de fundo explicitamente.

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

Regras CSS @page

Quando habilitado, as regras CSS @page no seu HTML substituem o tamanho de página e as margens configuradas no RenderOptions.

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

Seu HTML pode então controlar o layout:

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

Aguardando Conteúdo

Aguardar um Seletor DOM

Adie a renderização até que um elemento específico apareça no DOM. Útil quando JavaScript gera conteúdo dinamicamente.

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

Timeout

Defina o tempo máximo (em milissegundos) para aguardar o carregamento da página e a renderização. O padrão é 30000 (30 segundos).

$options = RenderOptions::create()
    ->setTimeout(60000);    // 60 seconds for heavy pages

Se o timeout for excedido, uma TimeoutException é lançada.

Exemplo Completo

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

Próximos Passos

• HTML Renderer -- Carregando conteúdo a partir de strings, arquivos e URLs.
• Recursos Avançados -- Mesclagem de PDFs, injeção de CSS, screenshots.