Memeriksa kondisi tata letak dengan NextPDF Connect

Sekilas pandang

Periksa kondisi tata letak dokumen selama sesi berlangsung agar Anda dapat mengambil keputusan penempatan dengan percaya diri. preview_layout — yang telah diverifikasi ulang terhadap registri alat server, tempat PreviewLayoutTool mengekspos nama protokol preview_layout — adalah kueri hanya-baca yang idempoten. Alat ini tidak merender PDF, tidak memajukan kursor, dan dapat dipanggil berapa kali pun. Semua alat berikut termasuk Core: create_pdf, set_font, add_text, preview_layout, add_page, dan output_pdf.

Pemasangan

composer require nextpdf/server

Ikat sebuah transport. Anda tidak memerlukan tingkat berlisensi.

Gambaran konseptual

preview_layout mengembalikan jumlah halaman, halaman saat ini, dimensi halaman, margin, dan posisi kursor — atribut geometri yang dimiliki halaman itu sendiri (ISO 32000-2 §7.7.3.3). Gunakan nilai tersebut untuk menghitung ruang vertikal yang tersisa:

remaining = page_height - bottom_margin - cursor_y

Jika remaining lebih besar daripada perkiraan tinggi blok berikutnya, lanjutkan di halaman saat ini. Jika tidak, panggil add_page terlebih dahulu. Karena panggilan ini bersifat hanya-baca, panggilan tersebut mengembalikan respons normal di setiap transport (PSR-18 §p2).

Permukaan API

Alat	Peran	Tingkat risiko
`create_pdf`	Membuka sesi	Aman
`set_font`	Menetapkan fon aktif	Hati-hati
`add_text`	Menulis teks, memajukan kursor	Hati-hati
`preview_layout`	Membaca kondisi tata letak (tanpa perubahan)	Aman
`add_page`	Menambahkan halaman saat ruang tidak cukup	Hati-hati
`output_pdf`	Merender dan mengembalikan PDF	Memerlukan Persetujuan / Tinjauan (base64)

Katalog alat adalah sumber rujukan resmi. Alat yang tersedia bagi Anda bergantung pada tingkat yang dipasang.

Contoh kode — Mulai cepat

create_pdf (Letter portrait) → document_id.
set_font (helvetica 14).
add_text ×3 (paragraf rata kiri-kanan).
preview_layout → baca page_dimensions, margins, cursor_position.
Hitung remaining; jika terlalu kecil, add_page.
add_text (bagian berikutnya).
output_pdf.

Contoh kode — Produksi

Panggil preview_layout sebelum blok apa pun jika Anda tidak yakin blok tersebut akan muat. Anggap kursor yang dikembalikan akurat untuk penulisan terakhir. Jika Anda mengubah fon, margin, atau tinggi baris sejak add_text terakhir, tulis probe singkat dan kueri ulang sebelum mengandalkan posisi yang diprediksi.

Kasus tepi & jebakan

Kursor usang setelah perubahan gaya. Posisi yang dilaporkan mencerminkan penulisan terakhir, bukan perubahan kondisi yang masih tertunda. Lakukan probe ulang jika presisi penting.
Sesi yang sudah dihancurkan. preview_layout gagal pada document_id yang sudah dihancurkan. Untuk memeriksa tata letak setelah keluaran, atur destroy: false pada output_pdf sebelumnya.
Teks kosong atau fon tidak dikenal. Galat validasi input standar berlaku.

Kinerja

preview_layout adalah operasi baca yang ringan. Profil untuk dokumen yang dihasilkan adalah structural.

Catatan keamanan

Kueri ini bersifat hanya-baca dan tidak memiliki efek samping. Koordinat yang dikembalikan tidak sensitif, tetapi perlakukan sebagai data dalam lingkup sesi.

Kesesuaian

Pernyataan	Spesifikasi	Klausul	reference_id
Objek halaman mendefinisikan atribut geometrinya.	ISO 32000-2	§7.7.3.3
Kueri hanya-baca mengembalikan respons transport normal.	PSR-18	§p2

Konteks komersial

Tidak berlaku — semua alat termasuk dalam Core.

Ketersediaan transport

Transport	Tersedia	Catatan
MCP (stdio)	Ya	`preview_layout` adalah `tools/call`.
REST	Ya	Operasi aman bergaya GET.
gRPC	Ya	Unary; idempoten.

Tingkat risiko HITL

preview_layout bersifat Aman (hanya-baca) dan tidak pernah memicu gerbang. create_pdf bersifat Aman. set_font, add_text, dan add_page bersifat Hati-hati. output_pdf bersifat Memerlukan Persetujuan, diturunkan ke Tinjauan dalam mode base64 (Tingkat risiko HITL).

Amplop JSON untuk gerbang konfirmasi

Pemeriksaan hanya-baca tidak pernah memicu gerbang:

{ "allowed": true }