NextPDF Connect에서 레이아웃 상태 검사하기

한눈에 보기

세션 도중 문서의 레이아웃 상태를 검사해 배치 위치를 결정할 수 있습니다. preview_layout은 서버 도구 레지스트리와 대조해 재검증되었으며, 여기서 PreviewLayoutTool이 프로토콜 이름 preview_layout을 노출합니다. 이는 읽기 전용 멱등 쿼리입니다. 이 쿼리는 PDF를 렌더링하지 않고, 커서를 진행시키지 않으며, 횟수 제한 없이 호출할 수 있습니다. 다음 도구는 모두 Core입니다: create_pdf, set_font, add_text, preview_layout, add_page, output_pdf.

설치

composer require nextpdf/server

전송 방식을 바인딩합니다. 라이선스 등급은 필요 없습니다.

개념 개요

preview_layout은 페이지 수, 현재 페이지, 페이지 크기, 여백, 커서 위치 등 페이지 자체의 기하 속성을 반환합니다(ISO 32000-2 §7.7.3.3). 이 값으로 남은 수직 공간을 계산합니다:

remaining = page_height - bottom_margin - cursor_y

remaining이 다음 블록의 예상 높이를 초과하면 현재 페이지에서 계속 진행합니다. 그렇지 않으면 먼저 add_page를 호출합니다. 이 호출은 읽기 전용이므로 모든 전송 방식에서 정상 응답을 반환합니다(PSR-18 §p2).

API 표면

도구	역할	위험 등급
`create_pdf`	세션 열기	Safe
`set_font`	활성 글꼴 설정	Caution
`add_text`	텍스트 쓰기, 커서 진행	Caution
`preview_layout`	레이아웃 상태 읽기(변경 없음)	Safe
`add_page`	공간이 부족할 때 페이지 추가	Caution
`output_pdf`	PDF 렌더링 및 반환	Approval Required / Review(base64)

도구 카탈로그가 공식 카탈로그입니다. 사용할 수 있는 도구는 설치된 등급에 따라 달라집니다.

코드 예제 — 빠른 시작

create_pdf(Letter 세로) → document_id.
set_font(helvetica 14).
add_text ×3(양쪽 정렬 문단).
preview_layout → page_dimensions, margins, cursor_position 읽기.
remaining 계산. 너무 작으면 add_page.
add_text(다음 섹션).
output_pdf.

코드 예제 — 프로덕션

현재 페이지에 들어갈지 확실하지 않은 블록 앞에서는 preview_layout을 호출합니다. 반환된 커서는 마지막 쓰기 기준으로 정확한 값으로 간주합니다. 마지막 add_text 이후 글꼴, 여백 또는 줄 높이를 변경했다면, 예측된 위치에 의존하기 전에 짧은 프로브를 작성하고 다시 조회합니다.

엣지 케이스 및 주의 사항

스타일 변경 후 오래된 커서. 보고된 위치는 대기 중인 상태 변경이 아니라 마지막 쓰기를 반영합니다. 정밀도가 중요하다면 프로브를 다시 수행합니다.
소멸된 세션. preview_layout은 소멸된 document_id에서는 실패합니다. 출력 후 레이아웃을 검사하려면 이전 output_pdf에 destroy: false를 설정합니다.
빈 텍스트 또는 알 수 없는 글꼴. 표준 입력 검증 오류가 적용됩니다.

성능

preview_layout은 비용이 낮은 읽기 작업입니다. 생성된 문서의 프로파일은 structural입니다.

보안 참고 사항

이 쿼리는 읽기 전용이며 부작용이 없습니다. 반환된 좌표는 민감하지 않지만, 세션 범위 데이터로 취급합니다.

적합성

진술	사양	절	reference_id
페이지 객체는 자체 기하 속성을 정의합니다.	ISO 32000-2	§7.7.3.3
읽기 전용 쿼리는 정상적인 전송 응답을 반환합니다.	PSR-18	§p2

상업적 맥락

해당 없음 — 모든 도구가 Core입니다.

전송 방식 가용성

전송 방식	가용 여부	참고
MCP (stdio)	예	`preview_layout`은 `tools/call`입니다.
REST	예	안전한 GET 스타일 작업입니다.
gRPC	예	단항(unary)이며 멱등입니다.

HITL 위험 등급

preview_layout은 Safe(읽기 전용)이며 게이트가 적용되지 않습니다. create_pdf는 Safe입니다. set_font, add_text, add_page는 Caution입니다. output_pdf는 Approval Required이며, base64 모드에서는 Review로 강등됩니다(HITL 위험 등급).

확인 게이트 JSON 엔벨로프

읽기 전용 검사에는 게이트가 적용되지 않습니다:

{ "allowed": true }