Размещение HTML-таблицы

Кратко

Используйте этот рецепт, чтобы отрисовать HTML-таблицу с заголовком, выровненными ячейками, границами и строкой нижнего колонтитула. Таблицы — проверенный модуль в матрице поддержки CSS. Рецепт следует файлу examples/09-html-table.php.

Установка

composer require nextpdf/core:^3

Это ограничение устанавливает пакет nextpdf/core. Пример рассчитан на PHP 8.4.

Концептуальный обзор

HTML-движок использует выделенный конвейер таблиц (src/Html/Table/). TableParser собирает строки и ячейки в недолговечном буфере, после чего NextPDF размещает и отрисовывает таблицу. Это единственное признанное отклонение от модели без сохраняемого DOM в ADR-001. Буфер недолговечен и ограничен своим контейнером. Это не постоянный DOM.

Ширина столбцов следует CSS-модели таблиц. NextPDF размещает таблицу при заданной используемой ширине, после чего алгоритм определения размеров столбцов задаёт используемую ширину каждого столбца (W3C CSS Table Level 3). При table-layout: fixed содержимое ячеек не учитывается при вычислении ширины. Вместо этого макет определяется первой строкой и явными значениями ширины столбцов (W3C CSS Table Level 3).

CSS Table Level 3 имеет в матрице оценку Verified. Эту оценку подтверждают четыре источника: src/Html/Table/, модульный набор тестов Table, тесты TableParser и синтетические эталонные PDF.

Поверхность API

Отрисовывайте таблицы с помощью writeHtml(string $html): static (NextPDF\Core\Concerns\HasTextOutput). Движок поддерживает стандартную табличную разметку. Поддерживаются теги table, thead, tbody, tfoot, tr, th и td. Поддерживаются атрибуты border, cellpadding, cellspacing, colspan и атрибут style на уровне ячейки. Полная таблица PHPDoc генерируется из исходного кода.

Пример кода — быстрый старт

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->addPage();

$doc->writeHtml(
    '<table border="1" cellpadding="5"><tr><th>SKU</th><th>Qty</th></tr>'
    . '<tr><td>NPD-CORE</td><td style="text-align: right;">1</td></tr></table>'
);

$doc->save(__DIR__ . '/out.pdf');

Пример кода — продакшен

Этот самодостаточный пример можно запустить в тестовом окружении. Он повторяет examples/09-html-table.php и демонстрирует стилизованный заголовок, чередующийся фон строк, выровненные числовые столбцы и итог в нижнем колонтитуле.

<?php

declare(strict_types=1);

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

use NextPDF\Core\Document;

$doc = Document::createStandalone();
$doc->setTitle('HTML Table');
$doc->addPage();

$html = <<<'HTML'
<h1 style="color: #1E3A8A;">Product Inventory Report</h1>

<table border="1" cellpadding="5" cellspacing="0" style="width: 100%;">
    <thead>
        <tr style="background-color: #1E3A8A; color: #FFFFFF;">
            <th style="width: 10%;">#</th>
            <th style="width: 45%;">Product</th>
            <th style="width: 20%; text-align: center;">SKU</th>
            <th style="width: 25%; text-align: right;">Price</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>1</td>
            <td>NextPDF Core License</td>
            <td style="text-align: center;">NPD-CORE</td>
            <td style="text-align: right;">$0.00</td>
        </tr>
        <tr style="background-color: #F8FAFC;">
            <td>2</td>
            <td>NextPDF Pro License</td>
            <td style="text-align: center;">NPD-PRO</td>
            <td style="text-align: right;">$299.00</td>
        </tr>
    </tbody>
    <tfoot>
        <tr style="background-color: #1E293B; color: #FFFFFF; font-weight: bold;">
            <td colspan="3" style="text-align: right;">Grand total:</td>
            <td style="text-align: right;">$299.00</td>
        </tr>
    </tfoot>
</table>
HTML;

$doc->writeHtml($html);

$out = getenv('NEXTPDF_COOKBOOK_OUTPUT');
$doc->save($out !== false ? $out : __DIR__ . '/html-table-layout.pdf');

echo "Wrote html-table-layout.pdf\n";

Ожидаемый стандартный вывод (STDOUT):

Wrote html-table-layout.pdf

Граничные случаи и подводные камни

Процентная ширина. Процентные значения width столбца вычисляются относительно используемой ширины таблицы. Алгоритм определения размеров столбцов нормализует процентные значения, если их сумма не равна 100. Не рассчитывайте на точную ширину в пикселях.
colspan. Объединённая ячейка участвует в распределении ширины по столбцам, которые она охватывает. Итог в нижнем колонтитуле, охватывающий большинство столбцов, — распространённый и поддерживаемый шаблон.
Модель границ. В некоторых тестовых наборах для таблиц значение border-collapse по умолчанию отличается от исходного значения в CSS. Задавайте его явно, когда важна отрисовка границ.
Объединение строк через разрывы страниц. Ячейка с объединением строк может пересекать границу страницы; в таком случае пагинатор объединения строк фрагментирует эту ячейку (ADR-007). Очень высокая ячейка, которую нельзя разбить, может вызвать UnsplittableContentException.
Пустые ячейки. Пустая <td> всё равно занимает свою ячейку сетки. Она не схлопывается.

Производительность

Буфер таблицы недолговечен и ограничен своим контейнером. Затраты на разбор линейны по числу ячеек, плюс проход определения размеров столбцов со сложностью O(rows x cols). Бюджет составляет wall_ms: 1500, peak_mb: 96. Держите одну таблицу в пределах ограничения ADR-020: 5,000 узлов на контекст.

Выдержка из матрицы поддержки CSS (только строки со статусом Verified)

Эта выдержка включает только строки со статусом Verified из проверенной матрицы поддержки CSS.

Модуль W3C	Уровень	Статус	Подтверждение
CSS Table — таблицы (`css_tables_3`)	3	Verified (проверено)	`src/Html/Table/`, `tests/Unit/Html/Table/` + тесты TableParser + эталонные PDF
CSS Flexible Box Layout — гибкие блоки (`css_flexbox_1`)	1	Verified (проверено)	`src/Html/Flex/`, `tests/Unit/Html/Flex/`
CSS Grid Layout — сеточная раскладка (`css_grid_1`)	1	Verified (проверено)	`src/Html/Grid/`, корпус WPT
CSS Cascading and Inheritance — каскад и наследование (`css_cascade_3`)	3	Verified (проверено)	`src/Html/Cascade/`

background-color, используемое здесь для чередования строк, имеет в матрице оценку “Claimed”. В рамках аудита Phase 0 его область действия — ячейка таблицы. Оно отрисовывается для строк таблицы, но не указано как Verified.

Ограничения однопроходной потоковой обработки (ADR-001)

Буфер таблицы — задокументированное исключение из потоковой модели. Он недолговечен и ограничен, а не является универсальным DOM. Не полагайтесь на таблицу как на источник контекста дерева для содержимого за её пределами.

Контракты слоёв (ADR-010)

FormattingContextFactory::startTable() читает CSS через контракт слоя макета. Он не разбирает необработанный $css[...] на пути диспетчеризации. Публичной поверхностью остаётся writeHtml().

Бюджет памяти для больших документов

Контекст форматирования таблицы ограничен 5,000 узлами и 20 уровнями вложенности в пределах потолка активной памяти в 50 MB (ADR-020). Разбейте очень большую таблицу на части или страницы. Не отрисовывайте её как один чрезмерно большой контекст.

Замечания по безопасности

Разметка таблиц из недоверенного ввода ограничена теми же лимитами на элементы и вложенность, что и остальной HTML. Проверяйте табличные данные, которые вводит пользователь. Отрисовщик не выполняет содержимое и при политике по умолчанию не загружает произвольные удалённые ресурсы.

Соответствие

Утверждение	Спецификация	Пункт	reference_id (идентификатор ссылки)
Используемая ширина столбцов определяется алгоритмом определения размеров столбцов таблицы при используемой ширине таблицы.	W3C CSS Table Level 3 (таблицы CSS, уровень 3)	css_tables_3#x1.x4.x9.x3 (раздел спецификации)
В фиксированном режиме содержимое ячеек не учитывается при вычислении ширины столбцов.	W3C CSS Table Level 3 (таблицы CSS, уровень 3)	css_tables_3#x1.x4.x5.x1.p6 (раздел спецификации)

Этот рецепт показывает, как NextPDF отрисовывает поддерживаемые HTML-таблицы. CSS Table Level 3 имеет статус Verified в матрице поддержки, а остальные используемые здесь модули CSS оцениваются по этой матрице.

Коммерческий контекст

Не применимо.