跳转到内容
NextPDF

让大型 HTML 表格跨页分页

概览

标题为“概览”的章节

将一个大型 <table> 传给 writeHtml()。引擎会按需要将它分页到任意多个 PDF 页面。<thead> 会在每页顶部重复，因此每一页都是一个完整的表格。本示例会渲染一份跨多页排布的 91 行报表。你无需手动拆分表格，也无需计算断点。

安装

标题为“安装”的章节
Terminal window
composer require nextpdf/core

概念总览

标题为“概念总览”的章节

当表格高度超过一页时，请将它保留为单个 <table> 元素。引擎会测量每一行，填满页面可用高度后另起新页，并继续渲染同一个表格。它会在每个续页顶部再次渲染 <thead> 行。续页会保留文档的上下边距，因此新页上的第一行从上边距下方开始，而不是贴着页面边缘。

请将表头单元格放在 <thead> 中，将数据行放在 <tbody> 中。只有 <thead> 会重复。请确保每一行都可拆分。单个高度超过可用页面高度的行无法分页，会引发 UnsplittableContentException。

API 一览

标题为“API 一览”的章节
符号位置作用
Document::writeHtml(string $html): staticNextPDF\Core\Concerns\HasTextOutput渲染 HTML，并按需对表格分页。
Document::createStandalone(): selfNextPDF\Core\Document创建一个独立文档。
Document::addPage(): staticNextPDF\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 3css_tables_3#x1.x7.x253622ccb1bce2a0cc53bd70919fa4633a9376e2050f63a31a3fde9cb6595ec78

商业情境

标题为“商业情境”的章节

不适用。

另请参阅

标题为“另请参阅”的章节