通过 NextPDF Connect 渲染 HTML 表格

概览

从 HTML 表格字符串中渲染结构化表格数据。add_table 会在布局前通过严格的 DOMDocument 允许列表净化输入，因此无论源标记如何编写，输出都能保持一致。这些工具包括 create_pdf、add_table 和 output_pdf，且全部属于 Core。表格会被布局为 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 以及其余属性。允许列表之外的任何标签都会被替换为其文本内容。单元格文本会使用文档当前的字体状态渲染；你需要在 add_table 之前通过 set_font 设置。文本由显示文本的运算符按内容流顺序输出（ISO 32000-2 §9.4）。列宽由布局引擎决定，而不是由内联 CSS 决定。

API 接口

工具	角色	风险层级
`create_pdf`	开启会话	安全
`set_font`	设置单元格文本字体（可选，需在 `add_table` 之前）	注意
`add_table`	净化并布局表格	注意
`output_pdf`	渲染并返回 PDF	需要批准/审查（base64）

工具目录是正式的工具目录依据。你可以使用的工具取决于已安装的层级。

代码示例——快速上手

create_pdf（A4 纵向、标题）→ document_id。
add_table 搭配一段完整的 <table>...</table> 字符串（表头行加上数据行）。
output_pdf → base64；或在带有 file_path 时，执行受控的文件写入。

光标会推进到最后一行已渲染内容的下方，为后续内容留出空间。

代码示例——正式环境

在发送 HTML 之前先验证它。通过 set_font 设置单元格字体，以获得可确定的排版；依赖默认值会使输出字体取决于实现。若要控制主机可调用哪些工具，请通过安全性原则限制登录权限。

边界情况与陷阱

空白或非表格 HTML。 不含 <table> 的输入会返回「无可渲染表格」错误。
标记格式错误。 未配对的标签会返回解析错误，因此请先验证结构。
表格比页面宽。 请减少列数、缩短内容，或切换为横向。
溢出。 过高的表格会流到新页面。请检查响应中的 position.page，或提前调用 add_page。

性能

小型表格可以在预算内完成渲染，输出约为数 KB。其可复现性配置文件为 structural。净化会对已解析的 DOM 执行单次处理。

安全性注意事项

属性会被无条件移除，且无法绕过。这可以防止通过单元格标记注入样式与脚本。任何内联 CSS、事件处理程序或 javascript: URL 都不会保留下来。允许列表就是信任边界，因此请勿将渲染后的输出视为对任意来源样式的忠实复现。

符合性

陈述	规格	条款	reference_id
表格会被布局为 row/column 单元格网格。	CSS Tables 3	§3.1
文本由文本运算符按内容流顺序显示。	ISO 32000-2	§9.4

商业背景

不适用——此处所有工具都属于 Core。

CSS 支持矩阵摘录（仅 Verified）

add_table 并不会运行通用的 CSS 引擎。唯一的「CSS」行为就是固定的表格网格模型：行与列来自表格结构，列宽由布局引擎选择。按设计不支持内联样式，因为属性会被移除。若需了解引擎级别（非 Connect）的 CSS 覆盖范围，请参阅项目的 CSS 支持矩阵。

单次串流限制

add_table 会将提供的标记一次性解析为 DOM，并通过单次处理完成布局。不会针对外部样式表重新排版。溢出页面的表格会推进到下一页，而不是事后重新排版。

大型表格的内存预算

非常大的表格会在整个调用期间，将已解析的 DOM 与已布局的单元格保留在内存中。请将大型数据集拆分为多次 add_table 调用，以保持在峰值内存预算以内。

传输可用性

传输	可用	备注
MCP（stdio）	是	大型 HTML 会导致 stdio 帧膨胀。
REST	是	在请求体中发送 HTML。
gRPC	是	单向；消息大小限制适用。

HITL 风险层级

create_pdf 为 Safe；set_font 与 add_table 为 Caution；output_pdf 为 Approval Required，在 base64 模式下降级为 Review。文件输出仍为 Approval Required——请参阅 output-approval。

确认关卡 JSON 信封

Base64 输出：

{ "allowed": true }

文件输出会返回 output-approval 中记录的挑战信封。