Render Options

Класс RenderOptions — неизменяемый объект значений, управляющий тем, как Chrome рендерит ваш HTML в PDF. Каждый сеттер возвращает новый экземпляр, делая конфигурацию предсказуемой и без побочных эффектов.

Создание опций

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

Применение опций

Передайте настроенный 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 (default)

Поддерживаемые форматы: 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%).

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

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

Колонтитулы

Chrome CDP поддерживает HTML-шаблоны для верхних и нижних колонтитулов. Шаблоны имеют доступ к специальным CSS-классам, которые Chrome заменяет динамическими значениями во время рендеринга.

Доступные 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

При включении CSS-правила @page в вашем HTML переопределяют размер страницы и поля, настроенные в 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 seconds for heavy pages

При превышении таймаута выбрасывается 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 Renderer -- Загрузка контента из строк, файлов и URL.
• Продвинутые функции -- Объединение PDF, внедрение CSS, скриншоты.