안정성: 실험적

페이지 미디어 CSS 프리뷰 플래그(GCPM 러닝 콘텐츠, 명명된 페이지, 페이지 플로트)

한눈에 보기

옵트인 프리뷰. 이 네 가지 CSS 기능은 기본적으로 꺼져 있습니다. 플래그가 꺼져 있으면, 엔진은 해당 기능이 존재하는 줄도 몰랐던 빌드와 바이트 단위로 동일한 출력을 만들어냅니다. 원할 때만 기능을 켜고, 여러분의 문서에 대해 결과를 검증하세요.

HTML 렌더러는 CSS Paged Media와 Generated Content for Paged Media(GCPM) 모듈에서 가져온 옵트인 페이지 미디어 기능 네 가지를 추가합니다. 각각은 CssFeatureFlags의 별도 플래그입니다. 각각은 정직한 fail-closed 경계를 지닙니다. 단일 패스 엔진이 충실하게 해석할 수 없는 구문은 이름이 붙은 진단과 함께 폐기되거나 격하되며, 결코 잘못 렌더링되지 않습니다.

기능	플래그	켜졌을 때 하는 일
명명된 문자열(GCPM)	`runningStrings`	`string-set` 캡처와 `@page` 마진 박스 안의 `string()` — 러닝 헤더와 푸터.
명명된 페이지(Paged Media L3)	`namedPagesAdvanced`	`@page <ident>`, `page:` 속성, 그리고 `:first` / `:left` / `:right` / `:blank` — 페이지별 마진 박스와 장식.
러닝 요소(GCPM)	`runningElements`	`position: running(<ident>)`와 `content: element(<ident>)` — 한 요소의 텍스트를 마진 박스에서 재생.
페이지 플로트(Page Floats L3)	`pageFloats`	`float: top \| bottom \| snap` — 박스를 페이지의 위쪽 또는 아래쪽 띠로 이동.

설치

composer require nextpdf/core:^3

플래그는 코어 패키지에 포함되어 제공됩니다. CssFeatureFlags 공개 표면은 @since 6.1.0입니다. 엔진 버전(Version::VERSION)은 변경되지 않습니다. 이 기능들은 추가적이며 기본적으로 꺼져 있습니다.

개념 개요

렌더러는 단일 패스이며 스트리밍 방식입니다(ADR-001 참조). 문서 트리를 유지하지 않으며 출력을 문서 순서대로 한 번만 씁니다. 이 제약은 여기 나오는 모든 기능의 형태를 결정합니다. 각 기능은 한 번의 전진 패스에서 볼 수 있는 것만 해석하고, 두 번째 패스나 유지된 트리가 필요한 모든 것에 대해 fail-closed 처리합니다. 그 경계는 숨겨지지 않고 문서화되어 있습니다 — 기능이 어디에서 멈추는지 아는 것이 그 기능을 사용하는 일의 일부입니다.

플래그를 true로 설정한 CssFeatureFlags를 생성해 Config에 전달하여 기능을 활성화합니다. 플래그가 꺼져 있으면, 해당 CSS는 지원되지 않는 속성과 똑같이 파싱되어 무시되므로, 출력은 그 기능이 없는 빌드와 바이트 단위로 동일합니다.

명명된 문자열 — `runningStrings`

string-set: <ident> content()는 엔진이 요소를 지나갈 때 값을 기록합니다. 그러면 @page 마진 박스 안의 string(<ident>) 참조가 그 페이지에서 가장 최근에 본 값으로 해석됩니다. 이는 현재 장이나 절을 추적하는 러닝 헤더를 위한 표준 메커니즘입니다.

해석은 단일 패스 “이 페이지에서 마지막으로 본 값” 방식입니다. string() 참조는 엔진이 해당 페이지의 마진 박스를 배치하기 전에 기록한 마지막 값으로 해석됩니다.

Fail-closed 경계. 플래그가 꺼져 있으면, string()은 빈 문자열로 해석되고 출력은 바이트 단위로 동일하게 유지됩니다. 형식이 잘못된 string-set 콘텐츠 목록은 그 하나의 할당 쌍을 폐기하고 계속 진행합니다. 렌더를 결코 중단하지 않습니다.

명명된 페이지 — `namedPagesAdvanced`

page: <ident> 속성은 요소를 명명된 페이지 컨텍스트에 할당하고, 일치하는 @page <ident> 규칙은 그 컨텍스트의 마진 박스와 페이지 장식을 공급합니다. 페이지 의사 클래스 :first, :left, :right, :blank는 각각 첫 페이지, recto 및 verso 페이지, 의도적으로 빈 페이지를 선택합니다.

이 기능은 명명된 페이지 또는 의사 페이지의 마진 박스와 장식을 선택합니다. 페이지 지오메트리는 변경하지 않습니다.

Fail-closed 경계. 지오메트리를 변경하려는 명명된 또는 의사 @page 규칙 — size, rotate, 또는 페이지 영역의 크기를 바꾸는 콘텐츠 박스 마진 — 은 잘못 정렬된 페이지를 조용히 만들어내는 대신 UnsupportedNamedPageException으로 fail-closed 처리됩니다. 의사 클래스 일치 채널이 첫 번째 슬라이스입니다. 더 넓은 셀렉터 사례는 연기되었으며 문서화되어 있습니다.

러닝 요소 — `runningElements`

position: running(<ident>)는 요소를 정상 흐름에서 제거하고 이름 아래에 주차합니다. 그러면 마진 박스 안의 content: element(<ident>)가 그 요소를 각 페이지에서 재생합니다. 헤더에 캡처된 문자열만이 아니라 제목의 완전한 스타일이 적용된 텍스트가 필요할 때 사용하세요.

Fail-closed 경계. 이 슬라이스는 러닝 요소의 텍스트만 재생합니다. 풍부한 콘텐츠 — 이미지, 대체 요소, 중첩 블록 구조 — 는 폐기되며, 엔진은 HTML_RUNNING_ELEMENT_DEGRADED 진단을 발행하여 그 손실이 조용히 묻히지 않고 보이게 합니다. 자기 자신을 참조하는 running() 요소, 중첩된 running(), 또는 내부 예산을 초과하는 캡처는 fail-closed 처리됩니다. 플래그가 꺼져 있으면 running()과 element()은 비활성 상태입니다.

페이지 플로트 — `pageFloats`

float: top, float: bottom, float: snap는 블록 축에서 박스를 페이지의 위쪽 또는 아래쪽 띠로 이동시키며, 띠의 높이를 예약하여 주변 텍스트가 예약된 영역 주위로 다시 흐르게 합니다.

float: bottom(그리고 아래쪽 띠로 해석되는 snap)은 단일 패스 엔진이 직접 처리하는 경우입니다. 박스는 캡처되어 페이지가 닫힐 때 페이지의 아래쪽 띠에 배치됩니다. float: top은 페이지 상단 띠로 축소됩니다.

Fail-closed 경계. 인라인 축의 snap(snap-inline)은 지원되지 않습니다. 이동할 수 없는 부작용을 지닌 박스 — 예를 들어 사각형이 흐름 위치에 묶여 있는 링크 주석 — 은 안전하게 재배치할 수 없으므로, 정상 흐름으로 되돌아가고 엔진은 그 대체를 설명하는 HTML_PAGE_FLOAT_* 진단을 발행합니다. 플래그가 꺼져 있으면 float: top | bottom | snap은 지원되지 않는 값으로 취급되어 무시됩니다.

API 표면

심볼	위치	역할
`CssFeatureFlags`	`src/Html/CssFeatureFlags.php`	불변 옵트인 플래그 집합. 생성자는 `runningStrings`, `namedPagesAdvanced`, `runningElements`, `pageFloats`를 받습니다(모두 기본값 `false`).
`Config::withCssFeatureFlags(CssFeatureFlags $flags): self`	`src/Core/Config.php`	플래그 집합을 문서 구성에 연결합니다.
`CssFeatureFlags::forMode(CssRenderingMode $mode, ?self $explicit = null): self`	`src/Html/CssFeatureFlags.php`	렌더링 모드에 대한 플래그 집합을 해석합니다(Safe 모드는 모든 플래그를 강제로 끄고, Normal 모드는 명시적 집합을 사용하거나, 아무것도 공급되지 않으면 `allEnabled()`를 사용합니다).
`UnsupportedNamedPageException`	`src/Html/PagedMedia/UnsupportedNamedPageException.php`	명명된/의사 `@page` 규칙이 페이지 지오메트리를 변경할 때 발생합니다.

진단 경고 코드는 렌더 결과의 어드바이저리 채널을 통해 표면화됩니다. HTML_RUNNING_ELEMENT_DEGRADED, HTML_RUNNING_ELEMENT_* 계열, 그리고 HTML_PAGE_FLOAT_* 계열입니다.

코드 샘플 — 빠른 시작

현재 장을 추적하는 러닝 헤더를 위해 명명된 문자열을 활성화합니다.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(
    new CssFeatureFlags(runningStrings: true),
);

$doc = Document::createStandalone($config);
$doc->addPage();
$doc->writeHtml(
    '<style>'
    . 'h2 { string-set: chapter content(); }'
    . '@page { @top-center { content: string(chapter); } }'
    . '</style>'
    . '<h2>Introduction</h2><p>Body text…</p>',
);
$doc->save(__DIR__ . '/running-header.pdf');

코드 샘플 — 프로덕션

여러 플래그를 함께 활성화하고, 어드바이저리 채널을 구문이 격하되었다는 신호로 취급하세요. 플래그들은 독립적입니다. 사용하는 것만 켜세요.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Config;
use NextPDF\Core\Document;
use NextPDF\Exception\UnsupportedNamedPageException;
use NextPDF\Html\Css\CssFeatureFlags;

$config = (new Config())->withCssFeatureFlags(new CssFeatureFlags(
    runningStrings: true,
    namedPagesAdvanced: true,
    runningElements: true,
    pageFloats: true,
));

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

try {
    $doc->writeHtml($html);
} catch (UnsupportedNamedPageException $e) {
    // A named @page rule tried to change page geometry (size/rotate/margin).
    // The engine fails closed rather than emit a misaligned page.
    throw $e;
}

$doc->save($out);

// Inspect $doc's advisory channel for HTML_RUNNING_ELEMENT_DEGRADED and
// HTML_PAGE_FLOAT_* before treating the output as final.

엣지 케이스 및 주의점

네 가지 플래그는 모두 독립적이며 기본적으로 꺼져 있습니다. 꺼진 플래그는 바이트 단위로 동일한 출력을 산출합니다. 사용하는 것만 활성화하세요.
runningStrings가 꺼져 있으면 string()은 비어 있습니다. 설계상 그렇습니다. 꺼진 경우에 대한 경고는 없습니다. 그것이 문서화된 기본값입니다.
러닝 요소는 텍스트만 재생합니다. 러닝 요소 안의 이미지와 중첩 블록은 HTML_RUNNING_ELEMENT_DEGRADED와 함께 폐기됩니다. 어드바이저리 채널을 확인하세요.
명명된 페이지는 지오메트리를 변경할 수 없습니다. 지오메트리를 변경하는 명명된/의사 @page 규칙은 UnsupportedNamedPageException을 던집니다. 페이지 크기와 회전은 명명된 @page 규칙이 아니라 Config를 통해 설정하세요.
페이지 플로트는 링크를 흐름 안에 유지합니다. 링크 주석을 담은 플로트된 박스는 HTML_PAGE_FLOAT_* 진단과 함께 정상 흐름으로 되돌아갑니다. 링크 사각형이 흐름 위치에 묶여 있기 때문입니다.

성능

각 기능은 제한된 양의 단일 패스 작업을 추가합니다. 명명된 문자열은 string-set 요소당 값 하나를 기록하고, 명명된 페이지는 페이지별 마진 박스 해석을 추가하며, 러닝 요소는 주차된 요소당 텍스트 버퍼 하나를 캡처하고, 페이지 플로트는 페이지당 띠 하나를 예약합니다. 어느 것도 문서 트리를 유지하지 않으므로, 스트리밍 렌더러의 O(중첩 깊이) 메모리 모델이 보존됩니다. 페이지당 performance_budget (wall_ms: 1500, peak_mb: 64)은 변경되지 않습니다.

보안 참고

이 플래그들은 입력 표면을 넓히지 않습니다. HTML 보안 정책, CSS 속성 허용 목록, 스타일시트 바이트 및 중첩 상한이 변경 없이 적용됩니다. 캡처된 문자열 및 요소 콘텐츠는 다른 모든 텍스트와 동일한 출력 경로를 통해 이스케이프됩니다. 이 기능들은 새로운 수집 채널이 아니라 레이아웃 동작을 추가합니다.

적합성

진술	사양	절
`string-set`는 명명된 문자열을 기록하고, `string()`은 페이지 마진 박스에서 그것을 해석합니다.	W3C CSS Generated Content for Paged Media	§3
`position: running()`은 요소를 흐름에서 제거하고, `content: element()`은 그것을 재생합니다.	W3C CSS Generated Content for Paged Media	§5
`page` 속성과 `@page <ident>`는 명명된 페이지 컨텍스트를 선택합니다.	W3C CSS Paged Media Module Level 3	§3
`float: top \| bottom \| snap`는 박스를 블록 축에서 페이지 띠로 플로트합니다.	W3C CSS Page Floats Level 3	§5

이는 워킹 그룹 모듈 기능의 프리뷰 구현입니다. NextPDF는 위에 문서화된 fail-closed 경계를 갖춘 단일 패스 부분집합을 구현합니다. 속성별 검증 상태는 CSS 지원 매트릭스에서 추적됩니다. 여기서는 종단 간 적합성을 주장하지 않습니다. 표준 텍스트는 재현되지 않습니다.