HTML 표 레이아웃 구성

한눈에 보기

이 레시피에서는 헤더, 정렬된 셀, 테두리, 바닥글 행을 포함한 HTML 표를 렌더링합니다. 표 기능은 CSS 지원 매트릭스에서 Verified 모듈로 분류됩니다. 이 레시피는 examples/09-html-table.php를 기준으로 합니다.

설치

composer require nextpdf/core:^3

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

개념 개요

HTML 엔진에는 전용 표 파이프라인(src/Html/Table/)이 있습니다. TableParser는 행과 셀을 수명이 짧은 버퍼에 모은 뒤, 표의 레이아웃을 계산하고 그립니다. 이는 ADR-001의 DOM 보존 없음 모델에서 유일하게 인정된 예외입니다. 이 버퍼는 수명이 짧고 해당 컨테이너로 범위가 제한됩니다. 영구적인 DOM이 아닙니다.

열 너비는 CSS Table 모델을 따릅니다. 표는 주어진 사용 너비를 기준으로 레이아웃되며, 이후 열 크기 조정 알고리즘이 각 열의 사용 너비를 설정합니다(W3C CSS Table Level 3). table-layout: fixed를 사용하면 너비 계산 시 셀 콘텐츠가 무시됩니다. 대신 첫 번째 행과 명시적인 열 너비가 레이아웃을 결정합니다(W3C CSS Table Level 3).

CSS Table Level 3은 매트릭스에서 Verified 등급으로 분류됩니다. 이 등급은 네 가지 출처로 뒷받침됩니다: src/Html/Table/, Table 단위 테스트 모음, TableParser 테스트, 합성 골든 PDF입니다.

API 표면

표는 writeHtml(string $html): static(NextPDF\Core\Concerns\HasTextOutput)을 통해 렌더링됩니다. 엔진은 표준 표 마크업을 지원합니다. 지원되는 태그는 table, thead, tbody, tfoot, tr, th, td입니다. 지원되는 속성은 border, cellpadding, cellspacing, colspan, 그리고 셀별 style입니다. 전체 PHPDoc 표는 소스에서 생성한 것입니다.

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

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

$doc->writeHtml(
    '<table border="1" cellpadding="5"><tr><th>SKU</th><th>Qty</th></tr>'
    . '<tr><td>NPD-CORE</td><td style="text-align: right;">1</td></tr></table>'
);

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

코드 샘플 — 프로덕션

이 예제는 독립적으로 실행 가능하며 하니스에서도 실행할 수 있습니다. examples/09-html-table.php를 그대로 반영하고, 스타일이 적용된 헤더, 번갈아 표시되는 행 배경, 정렬된 숫자 열, 바닥글 합계를 보여줍니다.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Table');
$doc->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Product Inventory Report</h1>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 10%;">#</th>
            <th style="width: 45%;">Product</th>
            <th style="width: 20%; text-align: center;">SKU</th>
            <th style="width: 25%; text-align: right;">Price</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>1</td>
            <td>NextPDF Core License</td>
            <td style="text-align: center;">NPD-CORE</td>
            <td style="text-align: right;">$0.00</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>2</td>
            <td>NextPDF Pro License</td>
            <td style="text-align: center;">NPD-PRO</td>
            <td style="text-align: right;">$299.00</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="background-color: #1E293B; color: #FFFFFF; font-weight: bold;">
            <td colspan="3" style="text-align: right;">Grand total:</td>
            <td style="text-align: right;">$299.00</td>
        </tr>
    </tfoot>
</table>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/html-table-layout.pdf');

echo "Wrote html-table-layout.pdf\n";

예상 STDOUT:

Wrote html-table-layout.pdf

에지 케이스 및 주의 사항

백분율 너비. 열 width 백분율은 사용 표 너비를 기준으로 해석됩니다. 열 크기 조정 알고리즘은 합계가 100이 되지 않는 백분율을 정규화합니다. 정확한 픽셀 너비를 가정하지 마십시오.
colspan. 병합된 셀은 자신이 차지하는 열 전체에 걸쳐 너비 분배에 참여합니다. 대부분의 열에 걸친 바닥글 합계는 일반적이며 지원되는 패턴입니다.
테두리 모델. 일부 표 픽스처에서는 border-collapse 기본값이 CSS 초기값과 다릅니다. 테두리 렌더링이 중요하다면 직접 설정하십시오.
페이지 나눔을 가로지르는 rowspan. rowspan이 적용된 셀은 페이지 경계를 가로지를 수 있으며, 이 경우 rowspan 페이지네이터가 해당 셀을 분할합니다(ADR-007). 분할할 수 없는 매우 높은 셀은 UnsplittableContentException을 발생시킬 수 있습니다.
빈 셀. 빈 <td>도 자신의 그리드 슬롯을 그대로 차지합니다. 접혀서 사라지지 않습니다.

성능

표 버퍼는 수명이 짧고 해당 컨테이너로 범위가 제한됩니다. 파싱 비용은 셀 수에 선형으로 비례하며, 여기에 O(rows x cols)의 열 크기 조정 패스가 추가됩니다. 예산은 wall_ms: 1500, peak_mb: 96입니다. 단일 표는 컨텍스트당 5,000개 노드라는 ADR-020 노드 한도 내로 유지하십시오.

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

이 발췌에는 Verified 행만 재현되어 있으며, 출처는 진실성 감사를 거친 CSS 지원 매트릭스입니다.

W3C 모듈	레벨	상태	증거
CSS Table 모듈 (`css_tables_3`)	3	Verified	`src/Html/Table/`, `tests/Unit/Html/Table/` + TableParser 테스트 + 골든 PDF
CSS Flexible Box Layout 모듈 (`css_flexbox_1`)	1	Verified	`src/Html/Flex/`, `tests/Unit/Html/Flex/`
CSS Grid Layout 모듈 (`css_grid_1`)	1	Verified	`src/Html/Grid/`, WPT 코퍼스
CSS Cascading and Inheritance 모듈 (`css_cascade_3`)	3	Verified	`src/Html/Cascade/`

background-color는 여기서 행 줄무늬에 사용되며, 매트릭스에서는 “Claimed” 등급입니다. Phase 0 감사에 따르면 적용 범위는 표 셀입니다. 표 행에도 렌더링되지만 Verified로 등재되어 있지는 않습니다.

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

표 버퍼는 스트리밍 모델에서 문서화된 예외입니다. 이는 일반적인 DOM이 아니라 수명이 짧고 경계가 정해진 구조입니다. 표가 표 외부 콘텐츠에 트리 컨텍스트를 제공한다고 가정하지 마십시오.

레이어 계약(ADR-010)

FormattingContextFactory::startTable()은 레이아웃 레이어의 계약을 통해 CSS를 읽습니다. 디스패치에서 원시 $css[...]를 파싱하지 않습니다. 공개 표면은 writeHtml()로 유지됩니다.

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

표 서식 컨텍스트는 50MB 활성 메모리 상한(ADR-020) 내에서 5,000개 노드와 20 레벨 깊이로 제한됩니다. 매우 큰 표는 분할하거나 페이지 단위로 나누십시오. 하나의 지나치게 큰 컨텍스트로 렌더링하지 마십시오.

보안 참고 사항

신뢰할 수 없는 입력에서 온 표 마크업은 다른 HTML과 동일한 요소 및 중첩 한도의 적용을 받습니다. 사용자가 구성하는 표 데이터는 검증하십시오. 렌더러는 콘텐츠를 실행하지 않으며, 기본 정책에서는 임의의 원격 리소스를 가져오지 않습니다.

적합성

진술	사양	절	참조 ID(reference_id)
사용 열 너비는 사용 표 너비를 기준으로 표 열 크기 조정 알고리즘에 의해 결정됩니다.	W3C CSS Table Level 3	css_tables_3#x1.x4.x9.x3
고정 모드에서는 열 너비 계산 시 셀 콘텐츠가 무시됩니다.	W3C CSS Table Level 3	css_tables_3#x1.x4.x5.x1.p6

이 레시피는 NextPDF가 지원되는 HTML 표를 렌더링하는 방식을 보여줍니다. CSS Table Level 3은 지원 매트릭스에서 Verified이며, 여기서 사용된 다른 CSS 모듈은 해당 매트릭스에 따라 등급이 매겨집니다.

상업적 맥락

해당 없음.