Отрисовка HTML-таблицы с помощью NextPDF Connect

Кратко

Отрисовка структурированных табличных данных из строки HTML-таблицы. add_table санитизирует входные данные с помощью DOMDocument и строгого белого списка до построения макета, поэтому результат остаётся предсказуемым даже при различиях в исходной разметке. Используйте Core-инструменты create_pdf, add_table и output_pdf. Таблица размещается как сетка row/column (CSS Tables 3 §3.1).

Установка

composer require nextpdf/server

Привяжите транспорт. Входные данные должны содержать корневой элемент <table> со строками <tr> и ячейками <th>/<td>.

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

add_table применяет фиксированный белый список элементов (table, thead, tbody, tfoot, tr, th, td, caption, b, i, u, strong, em, br, p, span). Все атрибуты удаляются у каждого элемента: style, class, width, colspan, rowspan, id и остальные. Любой тег вне белого списка заменяется своим текстовым содержимым. Для текста ячеек используется активное состояние шрифта документа, которое вы задаёте через set_font перед add_table. Текст выводится операторами показа текста в порядке потока содержимого (ISO 32000-2 §9.4). Ширину столбцов определяет движок макета, а не встроенный CSS.

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

Инструмент	Роль	Уровень риска
create_pdf	Открывает сессию	Безопасно
set_font	Задаёт шрифт текста ячеек (необязательно, перед add_table)	Осторожно
add_table	Санитизирует таблицу и строит её макет	Осторожно
output_pdf	Отрисовывает и возвращает PDF	Требуется одобрение / Проверка (base64)

Ориентируйтесь на Каталог инструментов. Доступные инструменты зависят от установленного уровня.

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

1. create_pdf (A4, книжная ориентация, заголовок) → document_id.
2. add_table с полной строкой <table>...</table> (строка заголовка и строки данных).
3. output_pdf → base64 или, при наличии file_path, защищённая запись в файл.

Курсор перемещается ниже последней отрисованной строки и оставляет место для следующего содержимого.

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

Проверьте HTML-разметку перед отправкой. Задайте шрифт ячеек через set_font для детерминированной типографики. Если вы полагаетесь на значение по умолчанию, шрифт результата зависит от реализации. Чтобы контролировать, какие инструменты может вызывать хост, ограничьте реестр политикой безопасности.

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

• Пустой или нетабличный HTML. Если во входных данных нет <table>, возвращается ошибка отсутствия таблицы для отрисовки.
• Некорректная разметка. При несбалансированных тегах возвращается ошибка разбора, поэтому сначала проверьте структуру.
• Таблица шире страницы. Уменьшите число столбцов, сократите содержимое или переключитесь на альбомную ориентацию.
• Переполнение. Высокая таблица переносится на новую страницу. Проверьте position.page в ответе или заранее вызовите add_page.

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

Небольшая таблица отрисовывается в пределах бюджета, а результат занимает несколько КБ. Профиль — structural. Санитизация выполняется за один проход по разобранному DOM.

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

Атрибуты удаляются безусловно, обойти это нельзя. Это защищает от внедрения стилей и скриптов через разметку ячеек. Ни встроенный CSS, ни обработчики событий, ни URL javascript: не сохраняются. Белый список служит границей доверия, поэтому не считайте отрисованный результат точным воспроизведением произвольного исходного оформления.

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

Утверждение	Спецификация	Раздел	Идентификатор ссылки (reference_id)
Таблицы размещаются в виде сетки ячеек row/column.	CSS Tables 3 (модель табличной разметки)	§3.1
Текст выводится операторами вывода текста в порядке потока.	ISO 32000-2	§9.4

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

Неприменимо — все инструменты здесь относятся к Core.

Фрагмент матрицы поддержки CSS (только проверенное)

add_table не запускает универсальный CSS-движок. Единственное “CSS”-поведение — фиксированная модель табличной сетки: строки и столбцы берутся из структуры таблицы, а ширину выбирает движок макета. Встроенное оформление намеренно не поддерживается, поскольку атрибуты удаляются. Сведения о поддержке CSS на уровне движка (вне Connect) см. в матрице поддержки CSS проекта.

Ограничение однопроходной потоковой обработки

add_table однократно разбирает переданную разметку в DOM и строит её макет за один проход. Он не выполняет повторную компоновку по внешним таблицам стилей. Таблица, переполняющая страницу, переходит на следующую страницу, а не перекомпоновывается задним числом.

Бюджет памяти для больших таблиц

Для очень больших таблиц разобранный DOM и скомпонованные ячейки остаются в памяти на протяжении всего вызова. Разбивайте крупные наборы данных на несколько вызовов add_table, чтобы оставаться в пределах бюджета пиковой памяти.

Доступность транспорта

Транспорт	Доступно	Примечания
MCP (stdio, стандартный ввод-вывод)	Да	Большой HTML увеличивает размер кадра stdio.
REST	Да	Отправляйте HTML в теле запроса.
gRPC	Да	Унарный; действуют ограничения на размер сообщения.

Уровень риска HITL

create_pdf — Безопасно; set_font и add_table — Осторожно; output_pdf — Требуется одобрение, понижается до Проверки в режиме base64. Вывод в файл остаётся на уровне “Требуется одобрение”. См. output-approval.

JSON-конверт шлюза подтверждения

Вывод в base64:

{ "allowed": true }

При выводе в файл возвращается конверт запроса подтверждения, описанный в output-approval.

См. также

• Типографика шрифтов
• Hello world (приветственный пример)
• Каталог инструментов