فحص حالة التخطيط باستخدام 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 }