대형 HTML 표를 여러 페이지로 나누기

한눈에 보기

하나의 대형 <table>을 writeHtml()에 전달하십시오. 엔진은 행에 필요한 만큼 표를 여러 PDF 페이지로 나눕니다. <thead>는 모든 페이지 상단에서 반복되므로, 각 페이지가 완전한 표처럼 동작합니다. 이 레시피는 여러 페이지에 걸쳐 이어지는 91행 보고서를 렌더링합니다. 사용자가 직접 표를 분할하거나 페이지 나누기를 계산할 필요는 없습니다.

설치

composer require nextpdf/core

개념 개요

표가 한 페이지보다 높을 때는 단일 <table> 요소로 유지하십시오. 엔진은 각 행을 측정하고, 사용 가능한 페이지 높이를 채운 뒤, 새 페이지를 열어 동일한 표를 계속 이어 갑니다. 엔진은 이어지는 각 페이지 상단에서 <thead> 행을 다시 렌더링합니다. 연속 페이지는 문서의 위쪽 및 아래쪽 여백을 유지하므로, 새 페이지의 첫 번째 행은 페이지 가장자리가 아니라 위쪽 여백 아래에서 시작합니다.

헤더 셀은 <thead>에, 데이터 행은 <tbody>에 배치하십시오. <thead>만 반복됩니다. 각 행은 분할 가능하게 유지하십시오. 사용 가능한 페이지 높이보다 높은 단일 행은 페이지로 나눌 수 없으며 UnsplittableContentException을 발생시킵니다.

API 표면

심볼	위치	역할
`Document::writeHtml(string $html): static`	`NextPDF\Core\Concerns\HasTextOutput`	HTML을 렌더링하고 필요에 따라 표를 여러 페이지로 나눕니다.
`Document::createStandalone(): self`	`NextPDF\Core\Document`	독립형 문서를 생성합니다.
`Document::addPage(): static`	`NextPDF\Core\Document`	첫 번째 페이지를 열고 페이지 크기와 여백을 설정합니다.

코드 샘플 — 빠른 시작

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$rows = '';
for ($i = 1; $i <= 91; $i++) {
    $rows .= "<tr><td>{$i}</td><td>Item {$i}</td><td>In stock</td></tr>";
}

$doc = Document::createStandalone();
$doc->addPage();
$doc->writeHtml(
    '<table>'
    . '<thead><tr><th>#</th><th>Name</th><th>Status</th></tr></thead>'
    . "<tbody>{$rows}</tbody>"
    . '</table>'
);
$doc->save(__DIR__ . '/large-table.pdf');

91개의 행이 여러 페이지에 걸쳐 이어지고, #/Name/Status 헤더가 각 페이지에서 반복됩니다.

코드 샘플 — 프로덕션

이 자체 완결형 예제는 헤더에 스타일을 적용하고, 행에 줄무늬를 넣으며, 하니스에서 제공한 경로에 PDF를 작성합니다.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$rows = '';
for ($i = 1; $i <= 91; $i++) {
    $bg = $i % 2 === 0 ? '#F8FAFC' : '#FFFFFF';
    $rows .= "<tr style=\"background-color: {$bg};\">"
        . "<td style=\"border: 1px solid #CBD5E1; padding: 4px;\">{$i}</td>"
        . "<td style=\"border: 1px solid #CBD5E1; padding: 4px;\">Item {$i}</td>"
        . "<td style=\"border: 1px solid #CBD5E1; padding: 4px;\">In stock</td>"
        . '</tr>';
}

$html = <<<HTML
<table style="width: 100%; border-collapse: collapse;">
  <thead>
    <tr style="background-color: #1E3A8A; color: #FFFFFF;">
      <th style="border: 1px solid #1E3A8A; padding: 6px;">#</th>
      <th style="border: 1px solid #1E3A8A; padding: 6px;">Name</th>
      <th style="border: 1px solid #1E3A8A; padding: 6px;">Status</th>
    </tr>
  </thead>
  <tbody>{$rows}</tbody>
</table>
HTML;

$doc = Document::createStandalone();
$doc->setTitle('Inventory report');
$doc->addPage();
$doc->writeHtml($html);

$out = getenv('NEXTPDF_OUT');
$doc->save($out !== false ? $out : __DIR__ . '/paginate-large-html-tables.pdf');

echo "Wrote the paginated table PDF\n";

연속 페이지 여백

연속 페이지는 문서의 위쪽 및 아래쪽 여백을 사용합니다. 페이지가 나뉜 뒤 첫 번째 행은 위쪽 여백 아래에서 시작하고, 나뉘기 전 마지막 행은 아래쪽 여백 위에서 멈춥니다. 이렇게 하면 긴 표가 페이지 가장자리에 맞닿아 잘리는 일이 없습니다. 동일한 규칙이 여러 페이지에 걸친 블록과 표에 적용됩니다.

엣지 케이스 및 주의 사항

성공적인 페이지 나누기는 경고 없이 처리됩니다. 표가 여러 페이지에 걸쳐 깔끔하게 이어질 때는 경고가 발생하지 않습니다. 엔진은 낮은 등급으로 처리된 레이아웃에 대해서만 TABLE_ROW_OVERFLOW 경고를 발생시킵니다. 즉, 페이지 나누기 싱크가 없거나, 행을 페이지 맨 앞으로 재배치해야 하는 경우입니다. 이 경고는 실패가 아니라 표를 단순화하라는 신호로 받아들이십시오.
헤더를 <thead>에 넣으십시오. <thead> 행만 반복됩니다. <tbody>에 남겨진 헤더 행은 한 번만 나타납니다.
행은 분할 가능해야 합니다. 사용 가능한 페이지 높이보다 높은 단일 행은 UnsplittableContentException을 발생시킵니다. 해당 행의 콘텐츠를 나누거나 줄이십시오.
rowspan은 나누기를 가로지르면 낮은 등급으로 처리됩니다. 페이지 경계를 가로지르는 rowspan 셀은 단편화됩니다(ADR-007). 페이지 나누기 경계를 넘어 온전하게 유지되어야 하는 그룹화에는 대신 카테고리 헤더 행을 사용하십시오. 지원되지 않는 CSS 기능을 참조하십시오.

성능

렌더링은 행 수에 따라 선형으로 확장됩니다. 엔진은 출력을 페이지 단위로 스트리밍하고 문서 트리를 유지하지 않으므로, 긴 표의 메모리 사용량은 페이지 수에 따라 증가하지 않습니다. 이 레시피의 예산은 wall_ms: 2000, peak_mb: 96입니다.

보안 참고 사항

출력 크기를 제한하려면 사용자가 제공한 데이터의 행 수와 셀 길이를 검증하십시오. 엔진은 텍스트를 해석하지 않고 렌더링하며, 어떤 스크립트도 실행하지 않습니다.

적합성

진술	사양	조항	reference_id
표 헤더 그룹은 표가 나뉘는 모든 단편화 컨테이너에서 반복됩니다.	W3C CSS Tables 3	css_tables_3#x1.x7.x2	53622ccb1bce2a0cc53bd70919fa4633a9376e2050f63a31a3fde9cb6595ec78

상업적 맥락

해당 없음.

함께 보기

HTML: HTML+CSS to PDF 렌더링 서브시스템 — 단일 패스 렌더링 및 페이지 나누기 동작.
HTML 표 레이아웃 구성하기 — 열 크기 조정, colspan, 테두리.
긴 HTML 콘텐츠를 여러 페이지로 나누기 — 혼합 블록 콘텐츠에 대한 페이지 나누기.
CSS 지원 매트릭스 — 표와 페이지 나누기의 지원 상태.