Inspecione o estado do layout no NextPDF Connect

Visão geral

Durante uma sessão, inspecione o estado do layout de um documento para tomar decisões de posicionamento com confiança. preview_layout — revalidada no registro de ferramentas do servidor, onde PreviewLayoutTool expõe o nome de protocolo preview_layout — é uma consulta de somente leitura e idempotente. Ela não renderiza um PDF, não avança o cursor e pode ser chamada quantas vezes for necessário. Todas essas ferramentas são Core: create_pdf, set_font, add_text, preview_layout, add_page e output_pdf.

Instalação

composer require nextpdf/server

Vincule um transporte. Você não precisa de uma camada licenciada.

Visão conceitual

preview_layout retorna a contagem de páginas, a página atual, as dimensões da página, as margens e a posição do cursor — os atributos de geometria próprios da página (ISO 32000-2 §7.7.3.3). Use esses valores para calcular o espaço vertical restante:

remaining = page_height - bottom_margin - cursor_y

Se remaining for maior que a altura estimada do próximo bloco, continue na página atual. Caso contrário, chame add_page primeiro. Como a chamada é de somente leitura, ela retorna uma resposta normal em todos os transportes (PSR-18 §p2).

Superfície da API

Ferramenta	Função	Camada de risco
`create_pdf`	Abre a sessão	Seguro
`set_font`	Define a fonte ativa	Cuidado
`add_text`	Escreve texto e avança o cursor	Cuidado
`preview_layout`	Lê o estado do layout (sem mutação)	Seguro
`add_page`	Anexa uma página quando o espaço se esgota	Cuidado
`output_pdf`	Renderiza e retorna o PDF	Aprovação obrigatória / Revisão (base64)

O catálogo de ferramentas é a fonte de referência. As ferramentas disponíveis para você dependem da camada instalada.

Exemplo de código — Início rápido

create_pdf (Letter retrato) → document_id.
set_font (helvetica 14).
add_text ×3 (parágrafos justificados).
preview_layout → consulte page_dimensions, margins, cursor_position.
Calcule remaining; se o valor for pequeno demais, add_page.
add_text (próxima seção).
output_pdf.

Exemplo de código — Produção

Chame preview_layout antes de qualquer bloco quando você não tiver certeza de que ele vai caber. Considere que o cursor retornado é preciso para a última escrita. Se você alterou a fonte, as margens ou a altura da linha desde o último add_text, escreva uma sondagem curta e consulte novamente antes de confiar na posição prevista.

Casos extremos e armadilhas

Cursor desatualizado após uma mudança de estilo. A posição informada reflete a última escrita, não mudanças de estado pendentes. Sonde novamente se a precisão for importante.
Sessão destruída. preview_layout falha com um document_id destruído. Para inspecionar o layout após gerar a saída, defina destroy: false no output_pdf anterior.
Texto vazio ou fonte desconhecida. Valem os erros padrão de validação de entrada.

Desempenho

preview_layout é uma operação de leitura barata. O perfil do documento produzido é structural.

Notas de segurança

A consulta é de somente leitura e não tem efeitos colaterais. As coordenadas retornadas não são sensíveis, mas trate-as como restritas ao escopo da sessão.

Conformidade

Declaração	Especificação	Cláusula	reference_id
Um objeto de página define seus próprios atributos de geometria.	ISO 32000-2	§7.7.3.3
Uma consulta de somente leitura retorna uma resposta de transporte normal.	PSR-18	§p2

Contexto comercial

Não aplicável — todas as ferramentas são Core.

Disponibilidade por transporte

Transporte	Disponível	Notas
MCP (stdio)	Sim	`preview_layout` é um `tools/call`.
REST	Sim	Uma operação segura no estilo GET.
gRPC	Sim	Unária; idempotente.

Camada de risco HITL

preview_layout é Seguro (somente leitura) e nunca exige aprovação. create_pdf é Seguro. set_font, add_text e add_page são Cuidado. output_pdf é Aprovação obrigatória, rebaixada para Revisão no modo base64 (camadas de risco HITL).

Envelope JSON do gate de confirmação

A inspeção de somente leitura nunca exige aprovação:

{ "allowed": true }