Pagine uma tabela HTML grande em várias páginas

Em resumo

Passe uma única <table> grande para writeHtml(). O motor distribui a tabela em tantas páginas PDF quantas as linhas exigirem. O <thead> se repete no topo de cada página, então cada página funciona como uma tabela completa. Esta receita renderiza um relatório de 91 linhas que flui por várias páginas. Você não divide a tabela por conta própria nem calcula as quebras de página.

Instalação

composer require nextpdf/core

Visão geral conceitual

Quando uma tabela é mais alta do que uma página, mantenha-a como um único elemento <table>. O motor mede cada linha, preenche a altura útil da página, abre uma nova página e continua a mesma tabela. Ele renderiza novamente as linhas do <thead> no topo de cada página de continuação. As páginas de continuação mantêm as margens superior e inferior do documento, então a primeira linha em uma nova página começa abaixo da margem superior, não na borda da página.

Coloque as células de cabeçalho em um <thead> e as linhas de dados em um <tbody>. Apenas o <thead> se repete. Garanta que cada linha possa ser dividida. Uma única linha mais alta do que a altura útil da página não pode ser paginada e lança UnsplittableContentException.

Superfície da API

Símbolo	Localização	Função
`Document::writeHtml(string $html): static`	`NextPDF\Core\Concerns\HasTextOutput`	Renderiza HTML e pagina tabelas conforme necessário.
`Document::createStandalone(): self`	`NextPDF\Core\Document`	Cria um documento autônomo.
`Document::addPage(): static`	`NextPDF\Core\Document`	Abre a primeira página e define o tamanho da página e as margens.

Exemplo de código — Início rápido

<?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');

As 91 linhas fluem por várias páginas, e o cabeçalho #/Name/Status se repete em cada página.

Exemplo de código — Produção

Este exemplo autossuficiente estiliza o cabeçalho, aplica faixas alternadas às linhas e grava o PDF no caminho fornecido pelo harness.

<?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";

Margens das páginas de continuação

As páginas de continuação usam as margens superior e inferior do documento. A primeira linha após uma quebra de página começa abaixo da margem superior, e a última linha antes de uma quebra para acima da margem inferior. Isso evita que uma tabela longa seja recortada na borda da página. A mesma regra se aplica a um bloco de várias páginas e a uma tabela de várias páginas.

Casos extremos e pegadinhas

Os avisos de paginação são silenciosos em caso de sucesso. Quando uma tabela flui corretamente pelas páginas, ela não emite nenhum aviso. O motor só lança um aviso TABLE_ROW_OVERFLOW em um layout degradado: quando não há um receptor de quebra de página ou quando uma linha precisa ser realocada para iniciar uma página. Trate o aviso como um sinal para simplificar a tabela, não como uma falha.
Coloque o cabeçalho no <thead>. Apenas as linhas do <thead> se repetem. Uma linha de cabeçalho mantida no <tbody> aparece uma única vez.
As linhas precisam ser divisíveis. Uma única linha mais alta do que a altura útil da página lança UnsplittableContentException. Divida o conteúdo dessa linha ou encurte-a.
rowspan degrada ao longo de uma quebra. Uma célula com rowspan que cruza um limite de página se fragmenta (ADR-007). Para agrupamentos que precisam permanecer intactos durante a paginação, use uma linha de cabeçalho de categoria em vez disso. Consulte Recursos CSS não suportados.

Desempenho

A renderização escala linearmente com o número de linhas. O motor faz streaming da saída página por página e nunca retém uma árvore de documento, então o uso de memória de uma tabela longa não cresce com a contagem de páginas. O orçamento desta receita é wall_ms: 2000, peak_mb: 96.

Notas de segurança

Valide a contagem de linhas e o comprimento das células dos dados enviados pelos seus usuários para manter o tamanho da saída limitado. O motor renderiza o texto em vez de interpretá-lo, e não executa nenhum script.

Conformidade

Declaração	Especificação	Cláusula	reference_id
Um grupo de cabeçalho de tabela se repete pelos contêineres de fragmentação em que uma tabela é dividida.	W3C CSS Tables 3	css_tables_3#x1.x7.x2	53622ccb1bce2a0cc53bd70919fa4633a9376e2050f63a31a3fde9cb6595ec78

Contexto comercial

Não aplicável.

Veja também

HTML: subsistema de renderização HTML+CSS para PDF — renderização em passagem única e comportamento de paginação.
Dispor tabelas em HTML — dimensionamento de colunas, colspan e bordas.
Paginar conteúdo HTML extenso — quebras de página para conteúdo em blocos mistos.
Matriz de suporte de CSS — status de suporte para tabelas e paginação.