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

トランスポートをバインドします。入力には、<tr> 行と <th>/<td> セルを含む <table> ルートを含める必要があります。

概念の概要

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	セッション開始	Safe
set_font	セルテキストのフォント設定（任意、add_table の前）	Caution
add_table	テーブルのサニタイズとレイアウト	Caution
output_pdf	PDF のレンダリングと返却	Approval Required / Review（base64）

正式なカタログは ツールカタログ です。利用できるツールは、インストール済みのティアによって異なります。

コードサンプル — クイックスタート

1. create_pdf（A4 縦、タイトル）→ document_id。
2. 完全な <table>...</table> 文字列（ヘッダー行とデータ行）を指定して add_table を呼び出します。
3. 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	対応	Unary、メッセージサイズ制限の適用

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 に記載のチャレンジエンベロープを返します。

関連項目

• フォントタイポグラフィ
• Hello world
• ツールカタログ