Paginar una tabla HTML extensa en varias páginas

De un vistazo

Pasar una única <table> grande a writeHtml(). El motor la pagina en tantas páginas PDF como requieran sus filas. El <thead> se repite en la parte superior de cada página, de modo que cada página puede leerse como una tabla completa. Esta receta renderiza un informe de 91 filas que fluye por varias páginas. No divide la tabla manualmente ni calcula los saltos de página.

Instalación

composer require nextpdf/core

Descripción conceptual

Cuando una tabla sea más alta que una página, mantenerla como un único elemento <table>. El motor mide cada fila, ocupa la altura útil de la página, abre una página nueva y continúa con la misma tabla. Vuelve a renderizar las filas <thead> en la parte superior de cada página de continuación. Las páginas de continuación conservan los márgenes superior e inferior del documento, por lo que la primera fila de una página nueva comienza por debajo del margen superior, no en el borde de la página.

Colocar las celdas de encabezado en un <thead> y las filas de datos en un <tbody>. Solo se repite el <thead>. Mantener cada fila divisible. Una fila individual más alta que la altura útil de la página no se puede paginar y lanza UnsplittableContentException.

Superficie de la API

Símbolo	Ubicación	Función
`Document::writeHtml(string $html): static`	`NextPDF\Core\Concerns\HasTextOutput`	Renderiza el HTML y pagina las tablas según sea necesario.
`Document::createStandalone(): self`	`NextPDF\Core\Document`	Crea un documento autónomo.
`Document::addPage(): static`	`NextPDF\Core\Document`	Abre la primera página y define el tamaño y los márgenes de la página.

Muestra de código — Inicio 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');

Las 91 filas fluyen por varias páginas, y el encabezado #/Name/Status se repite en cada página.

Muestra de código — Producción

Este ejemplo autónomo aplica estilos al encabezado, alterna el color de las filas y escribe el PDF en la ruta que proporciona el arnés.

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

Márgenes de las páginas de continuación

Las páginas de continuación usan los márgenes superior e inferior del documento. La primera fila después de un salto de página comienza por debajo del margen superior, y la última fila antes de un salto se detiene por encima del margen inferior. Esto evita que una tabla larga se recorte en el borde de la página. La misma regla se aplica tanto a un bloque de varias páginas como a una tabla de varias páginas.

Casos límite y trampas

La paginación no emite advertencias cuando todo va bien. Cuando una tabla fluye limpiamente por las páginas, no emite ninguna advertencia. El motor lanza una advertencia TABLE_ROW_OVERFLOW solo ante una maquetación degradada: cuando no hay un sumidero de salto de página o cuando una fila debe reubicarse al inicio de una página. Tratar la advertencia como una señal para simplificar la tabla, no como un fallo.
Coloca el encabezado en <thead>. Solo se repiten las filas de <thead>. Una fila de encabezado dejada en <tbody> aparece una sola vez.
Las filas deben ser divisibles. Una fila individual más alta que la altura útil de la página lanza UnsplittableContentException. Dividir el contenido de esa fila o acortarlo.
rowspan se degrada a través de un salto. Una celda con rowspan que cruza un límite de página se fragmenta (ADR-007). Para las agrupaciones que deben permanecer intactas durante la paginación, usar una fila de encabezado de categoría en su lugar. Consulta Funcionalidades de CSS no compatibles.

Rendimiento

El renderizado escala linealmente con el número de filas. El motor transmite la salida página por página y nunca retiene un árbol del documento, por lo que la memoria necesaria para una tabla larga no crece con el número de páginas. El presupuesto de esta receta es wall_ms: 2000, peak_mb: 96.

Notas de seguridad

Validar el número de filas y la longitud de las celdas en los datos proporcionados por el usuario para mantener acotado el tamaño de la salida. El motor renderiza el texto en lugar de interpretarlo y no ejecuta scripts.

Conformidad

Afirmación	Especificación	Cláusula	reference_id
Un grupo de encabezado de tabla se repite a lo largo de los contenedores de fragmentación en los que se divide una tabla.	W3C CSS Tables 3	css_tables_3#x1.x7.x2	53622ccb1bce2a0cc53bd70919fa4633a9376e2050f63a31a3fde9cb6595ec78

Contexto comercial

No aplicable.

Véase también

HTML: subsistema de representación de HTML+CSS a PDF — renderizado en una sola pasada y comportamiento de paginación.
Maquetar una tabla HTML — dimensionamiento de columnas, colspan y bordes.
Paginar HTML largo — saltos de página para contenido de bloque mixto.
Matriz de compatibilidad de CSS — estado de compatibilidad de tablas y paginación.