ตรวจสอบสถานะเค้าโครงด้วย NextPDF Connect

ภาพรวมโดยย่อ

ตรวจสอบสถานะเค้าโครงของเอกสารระหว่างเซสชัน เพื่อให้ตัดสินใจเรื่องการจัดตำแหน่งได้อย่างมั่นใจ preview_layout — ซึ่งได้รับการยืนยันซ้ำกับรีจิสทรีเครื่องมือของเซิร์ฟเวอร์ โดย PreviewLayoutTool เปิดเผยชื่อโปรโตคอล preview_layout — เป็นการสอบถามแบบอ่านอย่างเดียวและเป็น idempotent การสอบถามนี้ไม่เรนเดอร์ 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`	เปิดเซสชัน	ปลอดภัย
`set_font`	ตั้งค่าฟอนต์ที่ใช้งานอยู่	ควรระมัดระวัง
`add_text`	เขียนข้อความและเลื่อนเคอร์เซอร์	ควรระมัดระวัง
`preview_layout`	อ่านสถานะเค้าโครง (ไม่มีการเปลี่ยนแปลง)	ปลอดภัย
`add_page`	เพิ่มหน้าเมื่อพื้นที่หมด	ควรระมัดระวัง
`output_pdf`	เรนเดอร์และคืนค่า PDF	ต้องอนุมัติ / ตรวจทาน (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 ที่ถูกทำลายแล้ว หากต้องการตรวจสอบเค้าโครงหลังจากสร้างเอาต์พุต ให้ตั้งค่า destroy: false ใน output_pdf ก่อนหน้า
ข้อความว่างหรือฟอนต์ที่ไม่รู้จัก จะทำให้เกิดข้อผิดพลาดจากการตรวจสอบความถูกต้องของอินพุตตามมาตรฐาน

ประสิทธิภาพ

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	ใช่	แบบยูนารีและเป็น idempotent

ระดับความเสี่ยง HITL

preview_layout อยู่ในระดับปลอดภัย (อ่านอย่างเดียว) และไม่ถูกกั้นเพื่อขออนุมัติ create_pdf อยู่ในระดับปลอดภัย set_font, add_text และ add_page อยู่ในระดับควรระมัดระวัง ส่วน output_pdf อยู่ในระดับต้องอนุมัติ ซึ่งจะลดระดับเป็นการตรวจทานในโหมด base64 (ระดับความเสี่ยง HITL)

ซองข้อมูล JSON สำหรับเกตยืนยัน

การตรวจสอบแบบอ่านอย่างเดียวไม่ถูกกั้นเพื่อขออนุมัติ:

{ "allowed": true }