렌더링 옵션

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 주입, 스크린샷.