Разбиение большой 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 в PDF — однопроходная отрисовка и поведение при разбиении на страницы.
Размещение HTML-таблиц — определение размеров столбцов, colspan и границы.
Разбиение длинного HTML-содержимого на страницы — разрывы страниц для смешанного блочного содержимого.
Матрица поддержки CSS — статус поддержки таблиц и разбиения на страницы.