使用 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 所記載的挑戰信封。