CSS로 HTML 스타일 지정

한눈에 보기

이 레시피는 인라인 style 속성과 <style> 블록을 사용하여 HTML 콘텐츠에 CSS를 적용합니다. 또한 속성에 의존하기 전에 해당 속성의 지원 상태가 검증되었는지 확인하는 방법도 보여 줍니다.

설치

composer require nextpdf/core:^3

이 제약 조건은 nextpdf/core 패키지에 적용됩니다. 이 예제는 PHP 8.4에서 실행됩니다.

개념 개요

HTML 엔진은 CSS 종속(cascade)을 통해 스타일을 해석합니다. 종속은 여러 규칙이 같은 요소를 대상으로 할 때 어떤 스타일이 우선하는지 결정하는 규칙 집합입니다. 엔진은 입력에서 먼저 <style> 블록을 읽고, 그다음 인라인 style 속성을 읽습니다. 엔진은 둘을 모두 요소에 매칭한 뒤 종속 순서에 따라 결과를 계산합니다. 지원 매트릭스에서는 CSS Cascading and Inheritance 모듈을 Verified로 평가합니다. 이는 전용 픽스처 모음이 종속 및 상속 동작을 뒷받침한다는 뜻입니다.

텍스트 표현 속성인 text-align, text-indent, letter-spacing는 CSS Text 모듈 속성 표(W3C CSS Text Level 3)에서 가져옵니다. 글꼴 선택에는 CSS Fonts 모델을 사용합니다. font 단축 속성은 font-style, font-variant, font-weight, font-size, font-family를 함께 설정합니다(W3C CSS Fonts Level 3).

지원 여부는 각 W3C 모듈을 기준으로 하며 사실 기반으로 감사됩니다. 구현되었지만 전용 모듈 픽스처가 없는 속성은 “Verified”가 아니라 “Claimed”로 평가됩니다. “Claimed”는 최선의 노력으로 간주하고, 콘텐츠의 시각적 결과를 검증하십시오. “Verified”는 통과하는 픽스처 모음으로 뒷받침된다고 보십시오.

API 표면

모든 스타일 지정은 writeHtml(string $html): static(NextPDF\Core\Concerns\HasTextOutput)에 전달하는 HTML을 통해 제어합니다. 별도의 CSS API는 없으며, 종속은 내부에서 처리됩니다. 전체 PHPDoc 표는 소스에서 생성됩니다.

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->writeHtml(
    '<style>.lead { color: #1E3A8A; text-align: center; }</style>'
    . '<p class="lead">Styled with a style block.</p>'
);

$doc->save(__DIR__ . '/out.pdf');

코드 샘플 — 프로덕션

이 예제는 독립적으로 실행 가능하며 하니스에서도 실행할 수 있습니다. <style> 블록, 클래스 선택자, 인라인 스타일, 그리고 font 패밀리 및 가중치 경로를 사용합니다.

<?php

declare(strict_types=1);

require_once __DIR__ . '/vendor/autoload.php';

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('CSS Styling');
$doc->addPage();

$html = <<<'HTML'
<style>
    h1        { color: #1E3A8A; }
    .lead     { color: #D97706; font-size: 14px; }
    .callout  { background-color: #EFF6FF; padding: 8px; border: 1px solid #BFDBFE; }
    .centered { text-align: center; }
</style>

<h1>Styling HTML with CSS</h1>

<p class="lead">This paragraph is styled through a class selector in a
style block.</p>

<p class="callout">This paragraph has a background, padding, and a border
from a class selector.</p>

<p class="centered" style="font-weight: bold;">Centered, with an inline
override for weight.</p>

<p style="color: #6B7280; font-size: 9px;">Inline style only.</p>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/style-with-css.pdf');

echo "Wrote style-with-css.pdf\n";

예상 STDOUT:

Wrote style-with-css.pdf

엣지 케이스 및 주의 사항

종속 순서. 종속에 따라 동일한 명시도(specificity)에서는 인라인 style이 <style> 블록 선택자보다 우선합니다. 예상치 못한 색상이 보이면 먼저 인라인 재정의가 있는지 확인하십시오.
Claimed 대 Verified. 매트릭스에서 text-align, text-indent, color는 “Claimed”로 평가됩니다. 이들은 구현되었지만 전용 모듈 픽스처가 없습니다. 렌더링은 되지만, 프로덕션 승인을 위해서는 시각적 출력을 검증하십시오.
보존된 트리 없음. 스트리밍 엔진(ADR-001)은 문서 트리를 보존하지 않으므로, 뒤에 오는 형제 요소를 기준으로 앞선 요소를 다시 스타일 지정하는 선택자를 적용할 수 없습니다. 순서에 무관한 선택자는 제약을 받습니다.
지원되지 않는 속성. 지원되지 않는 속성은 오류를 발생시키지 않고 무시됩니다. 의존하기 전에 매트릭스와 대조하여 확인하십시오.
색 공간. Lab, LCH, OKLab 값은 파싱되지만, 해당 함수의 PDF 색 공간 충실도는 보장되지 않습니다(매트릭스: CSS Color 4에 대해 “Claimed”).

성능

종속 해결은 단일 패스의 일부입니다. 비용은 토큰 수에 대해 선형인 O(n)으로 유지됩니다. 예산은 wall_ms: 1500, peak_mb: 96입니다. <style> 블록은 규칙 수에 비례하는 일회성 선택자 파싱 비용을 추가합니다.

CSS 지원 매트릭스 발췌(Verified 행만)

이 발췌는 사실 기반으로 감사된 CSS 지원 매트릭스에서 Verified 행만 재현한 것입니다.

W3C 모듈	레벨	상태	증거
CSS Cascading and Inheritance (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`, `tests/Unit/Html/Cascade/`
CSS Cascading (`css_cascade_4`)	4	Verified	`Cascade/Layer/` + revert/layer 테스트
CSS Cascading (`css_cascade_5`)	5	Verified	`AtRule/Layer/` + `Cascade/Layer/` 모음
CSS Fonts (`css_fonts_3`)	3	Verified	`src/Html/Font/`, `tests/Unit/Font/` + FontResolver 테스트
CSS Fonts (`css_fonts_4`)	4	Verified	`src/Html/FontFace/`, `tests/Unit/Html/FontFace/`

text-align, text-indent, color, background-color는 매트릭스에서 “Claimed”입니다. 표에서는 의도적으로 이들을 Verified 행에서 제외합니다.

단일 패스 스트리밍 제약(ADR-001)

종속은 DOM 없이 스트리밍된 토큰 목록에 대해 실행되므로, 선택자는 문서 순서 컨텍스트를 기준으로 해결됩니다. 전체 트리 선택자 사례는 ADR-006에 따라 제약됩니다. 문서 순서와 상위 요소 컨텍스트에만 의존하는 CSS를 작성하십시오.

레이어 계약(ADR-010)

CSS 파싱은 종속 레이어에 속하며, 레이아웃 디스패치는 원시 $css[...] 값을 직접 읽어서는 안 됩니다. 공개 표면은 HTML 입력입니다. 종속을 우회하여 계산된 스타일을 주입하는 지원되는 방법은 없습니다.

대용량 문서를 위한 메모리 예산

종속은 노드 트리가 아니라 활성 규칙 집합과 푸시 및 팝 스타일 스택을 보관합니다. 컨테이너 범위 컨텍스트는 ADR-020 예산(컨텍스트당 5,000개 노드, 활성 상한 50 MB)을 따릅니다. 대용량 스타일시트는 규칙 집합 메모리를 선형으로 증가시키므로, 선택자 수를 제한된 범위로 유지하십시오.

보안 참고 사항

신뢰할 수 없는 HTML의 CSS는 코드를 실행할 수 없지만, 레이아웃과 리소스 참조(예: background-image)에 영향을 줄 수 있습니다. 기본 외부 리소스 정책은 임의의 원격 URL을 가져오지 않습니다. 사용자 입력으로 조합한 HTML과 CSS는 렌더링하기 전에 모두 새니타이즈하십시오.

적합성

설명	사양	조항	reference_id (참조 ID)
텍스트 속성(text-align, text-indent, letter-spacing)은 CSS Text 속성 표에서 정의됩니다.	W3C CSS Text Level 3	css_text_3#x1.x24
font 단축 속성은 font-style, font-variant, font-weight, font-size, font-family를 설정합니다.	W3C CSS Fonts Level 3	css_fonts_3#x2.x6.x7.p2

이 레시피는 NextPDF가 지원되는 CSS 하위 집합을 적용하는 방법을 보여 주며, 전체 CSS 지원을 보장하지는 않습니다. 모듈별 검증 상태는 CSS 지원 매트릭스를 참조하십시오.

상업적 컨텍스트

해당 없음.