Ispezionare lo stato del layout

In sintesi

Ispezionare lo stato del layout di un documento durante una sessione per decidere il posizionamento. La query preview_layout — verificata nuovamente rispetto al registro degli strumenti del server, dove PreviewLayoutTool espone il nome di protocollo preview_layout — è di sola lettura e idempotente. Non esegue il rendering di un PDF, non fa avanzare il cursore e può essere chiamata tutte le volte necessarie. Tutti questi strumenti sono Core: create_pdf, set_font, add_text, preview_layout, add_page e output_pdf.

Installazione

composer require nextpdf/server

Associare un trasporto. Non è necessario alcun livello con licenza.

Panoramica concettuale

preview_layout restituisce il numero di pagine, la pagina corrente, le dimensioni della pagina, i margini e la posizione del cursore, includendo gli attributi di geometria propri della pagina (ISO 32000-2 §7.7.3.3). A partire da questi valori, calcolare lo spazio verticale rimanente:

remaining = page_height - bottom_margin - cursor_y

Se remaining supera l’altezza stimata del blocco successivo, è possibile continuare nella pagina corrente. In caso contrario, chiamare prima add_page. Poiché è di sola lettura, la chiamata restituisce una risposta normale su ogni trasporto (PSR-18 §p2).

Superficie API

Strumento	Ruolo	Livello di rischio
`create_pdf`	Aprire una sessione	Attenzione
`set_font`	Impostare il font attivo	Attenzione
`add_text`	Scrivere testo e far avanzare il cursore	Attenzione
`preview_layout`	Leggere lo stato del layout (nessuna mutazione)	Sicuro
`add_page`	Aggiungere una pagina quando lo spazio si esaurisce	Attenzione
`output_pdf`	Eseguire il rendering e restituire il PDF	Approvazione richiesta / Revisione (base64)

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

Esempio di codice — Avvio rapido

create_pdf (Letter verticale) → document_id.
set_font (helvetica 14).
add_text ×3 (paragrafi giustificati).
preview_layout → leggere page_dimensions, margins, cursor_position.
Calcolare remaining; se troppo piccolo, add_page.
add_text (sezione successiva).
output_pdf.

Esempio di codice — Produzione

Chiamare preview_layout prima di qualsiasi blocco per cui non sia certo che rientri nello spazio disponibile. Considerare il cursore restituito attendibile rispetto all’ultima scrittura. Se il font, i margini o l’altezza di riga sono stati modificati dall’ultimo add_text, scrivere un breve testo di prova e ripetere la query prima di affidarsi alla posizione prevista.

Casi limite e insidie

Cursore obsoleto dopo una modifica di stile. La posizione segnalata riflette l’ultima scrittura, non eventuali modifiche di stato in sospeso. Ripetere la verifica se la precisione è importante.
Sessione distrutta. preview_layout fallisce con un document_id distrutto. Per ispezionare il layout dopo l’output, impostare destroy: false sull’output_pdf precedente.
Testo vuoto o font sconosciuto. Si applicano i normali errori di validazione dell’input.

Prestazioni

preview_layout è una lettura a basso costo. Il profilo del documento prodotto è structural.

Note sulla sicurezza

La query è di sola lettura e non ha effetti collaterali. Le coordinate restituite non sono sensibili, ma devono essere considerate confinate all’ambito della sessione.

Conformità

Dichiarazione	Specifica	Clausola
Un oggetto pagina definisce i propri attributi di geometria.	ISO 32000-2	§7.7.3.3
Una query di sola lettura restituisce una normale risposta di trasporto.	PSR-18	§p2

Contesto commerciale

Non applicabile — tutti gli strumenti sono Core.

Disponibilità del trasporto

Trasporto	Disponibile	Note
MCP (stdio)	Sì	`preview_layout` è una `tools/call`.
REST	Sì	Operazione sicura in stile GET.
gRPC	Sì	Chiamata unaria; idempotente.

Livello di rischio HITL

preview_layout è Sicuro (sola lettura) e non blocca mai. create_pdf è Attenzione. set_font, add_text e add_page sono Attenzione. output_pdf è Approvazione richiesta, con declassamento a Revisione in modalità base64 (livelli di rischio HITL).

Involucro JSON del gate di conferma

L’ispezione di sola lettura non viene mai bloccata:

{ "allowed": true }