Renderizzare una tabella HTML con NextPDF Connect

In sintesi

Renderizzare dati tabulari strutturati a partire da una stringa di tabella HTML. add_table sanifica l’input tramite un’allowlist rigorosa basata su DOMDocument prima del layout, in modo che l’output rimanga coerente a prescindere da come è scritto il markup di origine. Gli strumenti sono create_pdf, add_table e output_pdf — tutti Core. La tabella viene disposta come una griglia row/column (CSS Tables 3 §3.1).

Installazione

composer require nextpdf/server

Configurare un trasporto. L’input deve contenere un elemento radice <table> con righe <tr> e celle <th>/<td>.

Panoramica concettuale

add_table applica un’allowlist fissa di elementi (table, thead, tbody, tfoot, tr, th, td, caption, b, i, u, strong, em, br, p, span). Tutti gli attributi vengono rimossi da ogni elemento — style, class, width, colspan, rowspan, id e ogni altro attributo. Qualsiasi tag al di fuori dell’allowlist viene sostituito con il proprio contenuto testuale. Il testo delle celle viene reso con lo stato del font attivo del documento, da impostare con set_font prima di add_table. Il testo viene emesso dagli operatori di visualizzazione del testo nell’ordine del flusso di contenuto (ISO 32000-2 §9.4). Le larghezze delle colonne sono decise dal motore di layout, non dal CSS inline.

Superficie API

Strumento	Ruolo	Livello di rischio
`create_pdf`	Aprire una sessione	Sicuro
`set_font`	Impostare il font del testo delle celle (facoltativo, prima di `add_table`)	Attenzione
`add_table`	Sanificare e disporre la tabella	Attenzione
`output_pdf`	Eseguire il rendering e restituire il PDF	Approvazione richiesta / Revisione (base64)

Il catalogo degli strumenti è il riferimento per il catalogo. Gli strumenti disponibili dipendono dal livello installato.

Esempio di codice — Avvio rapido

create_pdf (A4 verticale, titolo) → document_id.
add_table con una stringa <table>...</table> completa (riga di intestazione e righe di dati).
output_pdf → base64 oppure, con un file_path, una scrittura su file sottoposta a gate.

Il cursore avanza sotto l’ultima riga resa, lasciando spazio per il contenuto che segue.

Esempio di codice — Produzione

Convalidare l’HTML prima di inviarlo. Impostare il font delle celle con set_font per una resa tipografica deterministica — affidarsi a un valore predefinito rende il font dell’output dipendente dall’implementazione. Per controllare quali strumenti l’host può invocare, limitare il registry tramite il criterio di sicurezza.

Casi limite e insidie

HTML vuoto o non tabellare. Un input senza <table> restituisce un errore perché la tabella non è renderizzabile.
Markup malformato. I tag non bilanciati causano un errore di parsing, quindi convalidare prima la struttura.
Tabella più larga della pagina. Ridurre le colonne, accorciare il contenuto o passare all’orientamento orizzontale.
Overflow. Una tabella alta continua su una nuova pagina. Controllare position.page nella risposta, oppure chiamare add_page in anticipo.

Prestazioni

Una tabella piccola viene resa entro il budget e l’output pesa pochi KB. Il profilo è structural. La sanificazione viene eseguita in un unico passaggio sul DOM analizzato.

Note sulla sicurezza

La rimozione degli attributi è incondizionata e non può essere aggirata. Questa scelta protegge dall’iniezione di stili e script tramite il markup delle celle. Nessun CSS inline, gestore di eventi o URL javascript: sopravvive. L’allowlist è il confine di fiducia, quindi non considerare l’output reso come una riproduzione fedele degli stili arbitrari di origine.

Conformità

Dichiarazione	Specifica	Clausola	reference_id
Le tabelle vengono disposte come una griglia di celle row/column.	CSS Tables 3	§3.1
Il testo viene visualizzato dagli operatori di testo nell’ordine del flusso.	ISO 32000-2	§9.4

Contesto commerciale

Non applicabile — tutti gli strumenti qui sono Core.

Estratto della matrice di supporto CSS (solo Verified)

add_table non esegue alcun motore CSS generico. L’unico comportamento «CSS» è il modello a griglia fissa della tabella: righe e colonne provengono dalla struttura della tabella e il motore di layout sceglie le larghezze. Lo stile inline non è supportato per scelta progettuale, perché gli attributi vengono rimossi. Per la copertura CSS a livello di motore (non Connect), consultare la matrice di supporto CSS del progetto.

Vincolo di streaming a passaggio singolo

add_table analizza il markup fornito in un DOM una sola volta e lo dispone in un unico passaggio. Non viene eseguito alcun reflow sulla base di fogli di stile esterni. Una tabella che eccede la pagina continua nella pagina successiva anziché eseguire un reflow retroattivo.

Budget di memoria per tabelle di grandi dimensioni

Per le tabelle molto grandi, il DOM analizzato e le celle disposte restano in memoria per l’intera chiamata. Suddividere i dataset di grandi dimensioni su più chiamate add_table per rimanere entro il budget di memoria di picco.

Disponibilità dei trasporti

Trasporto	Disponibile	Note
MCP (stdio)	Sì	Un contenuto HTML di grandi dimensioni gonfia il frame stdio.
REST	Sì	Inviare l’HTML nel corpo della richiesta.
gRPC	Sì	Chiamata unaria; si applicano i limiti di dimensione dei messaggi.

Livello di rischio HITL

create_pdf è Sicuro; set_font e add_table sono Attenzione; output_pdf richiede Approvazione richiesta, declassata a Revisione in modalità base64. L’output su file rimane Approvazione richiesta — vedere output-approval.

Envelope JSON del gate di conferma

Output Base64:

{ "allowed": true }

L’output su file restituisce l’envelope di challenge documentato in output-approval.