Inspeccionar el estado de diseño con NextPDF Connect

De un vistazo

Inspeccionar el estado de diseño de un documento durante la sesión para tomar decisiones de posicionamiento. preview_layout —comprobada de nuevo en el registro de herramientas del servidor, donde PreviewLayoutTool expone el nombre de protocolo preview_layout— es una consulta de solo lectura e idempotente. No renderiza un PDF, no avanza el cursor y se puede llamar tantas veces como sea necesario. Todas estas herramientas son Core: create_pdf, set_font, add_text, preview_layout, add_page y output_pdf.

Instalación

composer require nextpdf/server

Vincular un transporte. No se requiere ningún nivel con licencia.

Descripción conceptual

preview_layout devuelve el número de páginas, la página actual, las dimensiones de la página, los márgenes y la posición del cursor: los atributos de geometría propios de la página (ISO 32000-2 §7.7.3.3). A partir de esos valores, calcular el espacio vertical restante:

remaining = page_height - bottom_margin - cursor_y

Si remaining supera la altura estimada del siguiente bloque, continuar en la página actual. De lo contrario, llamar primero a add_page. Como la llamada es de solo lectura, devuelve una respuesta normal en todos los transportes (PSR-18 §p2).

Superficie de la API

Herramienta	Rol	Nivel de riesgo
`create_pdf`	Abrir la sesión	Seguro
`set_font`	Establecer la fuente activa	Precaución
`add_text`	Escribir texto, avanzar el cursor	Precaución
`preview_layout`	Leer el estado del diseño (sin mutación)	Seguro
`add_page`	Añadir una página cuando se agota el espacio	Precaución
`output_pdf`	Renderizar y devolver el PDF	Aprobación requerida / Revisión (base64)

El catálogo de herramientas es la referencia. Las herramientas disponibles dependen del nivel instalado.

Ejemplo de código — Inicio rápido

create_pdf (Letter vertical) → document_id.
set_font (helvetica 14).
add_text ×3 (párrafos justificados).
preview_layout → leer page_dimensions, margins, cursor_position.
Calcular remaining; si es demasiado pequeño, add_page.
add_text (siguiente sección).
output_pdf.

Ejemplo de código — Producción

Llamar a preview_layout antes de cualquier bloque cuyo ajuste sea incierto. Tratar el cursor devuelto como exacto para la última escritura. Si se cambiaron la fuente, los márgenes o la altura de línea desde la última add_text, escribir una sonda breve y volver a consultar antes de confiar en la posición prevista.

Casos límite y trampas

Cursor obsoleto tras un cambio de estilo. La posición notificada refleja la última escritura, no los cambios de estado pendientes. Volver a consultar si la precisión es importante.
Sesión destruida. preview_layout falla con un document_id destruido. Para inspeccionar el diseño después de la salida, establecer destroy: false en el output_pdf anterior.
Texto vacío o fuente desconocida. Se aplican los errores estándar de validación de entrada.

Rendimiento

preview_layout es una lectura de bajo costo. El perfil del documento generado es structural.

Notas de seguridad

La consulta es de solo lectura y no tiene efectos secundarios. Las coordenadas devueltas no son sensibles, pero deben tratarse como limitadas al ámbito de la sesión.

Conformidad

Declaración	Especificación	Cláusula	reference_id
Un objeto de página define sus atributos de geometría.	ISO 32000-2	§7.7.3.3
Una consulta de solo lectura devuelve una respuesta de transporte normal.	PSR-18	§p2

Contexto comercial

No aplicable: todas las herramientas son Core.

Disponibilidad por transporte

Transporte	Disponible	Notas
MCP (stdio)	Sí	`preview_layout` es un `tools/call`.
REST	Sí	Operación segura de estilo GET.
gRPC	Sí	Unaria; idempotente.

Nivel de riesgo HITL

preview_layout es Seguro (solo lectura) y nunca aplica un gate. create_pdf es Seguro. set_font, add_text y add_page son Precaución. output_pdf es Aprobación requerida, degradado a Revisión en modo base64 (niveles de riesgo HITL).

Envoltorio JSON del gate de confirmación

La inspección de solo lectura nunca aplica un gate:

{ "allowed": true }