Yerleşim durumunu inceleyin

Bir bakışta

Bir oturum sırasında belgenin yerleşim durumunu inceleyerek konumlandırma kararlarını güvenle verin. Sunucunun araç kayıt defterine göre yeniden doğrulanan preview_layout — burada PreviewLayoutTool, preview_layout protokol adını sunar — salt okunur ve idempotent bir sorgudur. PDF’i işlemez, imleci ilerletmez ve istediğiniz kadar çağrılabilir. Bu araçların tamamı Core kapsamındadır: create_pdf, set_font, add_text, preview_layout, add_page ve output_pdf.

Kurulum

composer require nextpdf/server

Bir taşıma katmanı bağlayın. Lisanslı bir katman gerekmez.

Kavramsal genel bakış

preview_layout, sayfa sayısını, geçerli sayfayı, sayfa boyutlarını, kenar boşluklarını ve imleç konumunu, yani sayfanın kendi geometri özniteliklerini döndürür (ISO 32000-2 §7.7.3.3). Kalan dikey alanı hesaplamak için bu değerleri kullanın:

remaining = page_height - bottom_margin - cursor_y

Eğer remaining değeri sonraki bloğunuzun tahmini yüksekliğinden büyükse geçerli sayfada devam edin. Aksi takdirde önce add_page çağrısını yapın. Çağrı salt okunur olduğu için her taşıma katmanında normal bir yanıt döndürür (PSR-18 §p2).

API yüzeyi

Araç	Rol	Risk düzeyi
`create_pdf`	Oturumu başlatır	Dikkat
`set_font`	Etkin yazı tipini ayarlar	Dikkat
`add_text`	Metin yazar ve imleci ilerletir	Dikkat
`preview_layout`	Yerleşim durumunu okur (değişiklik yapmaz)	Güvenli
`add_page`	Alan dolduğunda sayfa ekler	Dikkat
`output_pdf`	PDF’i işler ve döndürür	Onay gerekli / inceleme (base64)

Kayıt kaynağı araç kataloğudur. Kullanabileceğiniz araçlar kurulu katmana bağlıdır.

Kod örneği — hızlı başlangıç

create_pdf (Letter dikey) → document_id.
set_font (helvetica 14).
add_text ×3 (iki yana yaslı paragraflar).
preview_layout → page_dimensions, margins ve cursor_position değerlerini okuyun.
Önce remaining değerini hesaplayın; çok küçükse add_page çağırın.
add_text (sonraki bölüm).
output_pdf.

Kod örneği — Üretim

Sığacağından emin olmadığınız her bloktan önce preview_layout çağrısını yapın. Döndürülen imleci yalnızca son yazma işlemi için doğru kabul edin. Son add_text çağrısından bu yana yazı tipini, kenar boşluklarını veya satır yüksekliğini değiştirdiyseniz tahmini konuma güvenmeden önce kısa bir sınama metni yazın ve yeniden sorgulayın.

Sınır durumları ve tuzaklar

Stil değişikliğinden sonra güncelliğini yitirmiş imleç. Bildirilen konum, bekleyen durum değişikliklerini değil son yazmayı yansıtır. Kesinlik önemliyse yeniden sınama yapın.
Yok edilmiş oturum. preview_layout, yok edilmiş bir document_id verildiğinde başarısız olur. Çıktıdan sonra yerleşimi incelemek için destroy: false değerini bir önceki output_pdf çağrısında ayarlayın.
Boş metin veya bilinmeyen yazı tipi. Standart giriş doğrulama hataları geçerlidir.

Performans

preview_layout, düşük maliyetli bir okuma işlemidir. Üretilen belgenin profili structural türündedir.

Güvenlik notları

Sorgu salt okunurdur ve hiçbir yan etkisi yoktur. Döndürülen koordinatlar hassas değildir, ancak bunları oturumla sınırlı kabul edin.

Uyumluluk

İfade	Spesifikasyon	Madde
Bir sayfa nesnesi kendi geometri özniteliklerini tanımlar.	ISO 32000-2	§7.7.3.3
Salt okunur bir sorgu, normal bir taşıma yanıtı döndürür.	PSR-18	§p2

Ticari bağlam

Geçerli değil — tüm araçlar Core kapsamındadır.

Taşıma katmanı kullanılabilirliği

Taşıma katmanı	Kullanılabilir	Notlar
MCP (stdio)	Evet	`preview_layout`, bir `tools/call` çağrısıdır.
REST	Evet	Güvenli, GET tarzında bir işlem.
gRPC	Evet	Tekli (unary); idempotent.

HITL risk düzeyi

preview_layout güvenli (salt okunur) düzeydedir ve hiçbir zaman onay kapısı oluşturmaz. create_pdf dikkat düzeyindedir. set_font, add_text ve add_page dikkat düzeyindedir. output_pdf onay gerekli düzeyindedir; base64 modunda inceleme düzeyine düşürülür (HITL risk düzeyleri).

Onay kapısı JSON zarfı

Salt okunur inceleme hiçbir zaman onay kapısı oluşturmaz:

{ "allowed": true }