إنشاء مستند متعدد الصفحات باستخدام NextPDF Connect

لمحة عامة

أنشئ مستندًا متعدد الصفحات باستخدام ⁨NextPDF Connect.⁩ يُلحِق add_page صفحةً ترث هندسة الصفحة الافتراضية للمستند، أو يعيّن لها اتجاهًا خاصًا. بعد كل add_page، يُعاد ضبط المؤشر إلى الهامش العلوي الأيسر في الصفحة الجديدة. تستخدم هذه الوصفة أربع أدوات من ⁨Core⁩: create_pdf وadd_text وadd_page وoutput_pdf.

التثبيت

composer require nextpdf/server

اربط وسيلة نقل: ⁨Model Context Protocol⁩ (⁨MCP⁩) ⁨stdio⁩ أو ⁨REST⁩ أو ⁨gRPC.⁩ لا تحتاج إلى مستوى مرخَّص.

نظرة مفاهيمية

يستخدم المستند شجرة صفحات. تصل إلى كل صفحة عبر تلك الشجرة (⁨ISO 32000-2⁩ §7.7.3). لكل صفحة سمات هندسية خاصة بها، بما في ذلك صندوق الوسائط الذي يحدد المساحة المرئية (⁨ISO 32000-2⁩ §7.7.3.3). ينشئ create_pdf الصفحة الأولى تلقائيًا، ويُلحِق add_page كل صفحة إضافية. احذف page_size/orientation لترث الصفحة الإعداد الافتراضي للمستند. اضبط orientation: "landscape" لتصبح صفحة ⁨A4⁩ بقياس 297×210 ⁨mm.⁩

واجهة ⁨API⁩

الأداة	الدور	مستوى الخطورة
create_pdf	فتح الجلسة وإنشاء الصفحة الأولى	آمن
add_text	كتابة النص عند المؤشر	تنبيه
add_page	إلحاق صفحة (توريث أو تجاوز)	تنبيه
output_pdf	تصيير ⁨PDF⁩ وإرجاعه	موافقة مطلوبة / مراجعة (⁨base64⁩)

أسماء الأدوات هي أسماء البروتوكول الموثَّقة في السجل. يُعَدّ كتالوج الأدوات المرجع المعتمد. تعتمد الأدوات المتاحة لك على المستوى المثبَّت.

مثال برمجي — بداية سريعة

بصيغة وصفية:

1. create_pdf (⁨A4⁩ عمودي، عنوان، مؤلف) ← document_id.
2. add_text (العنوان، خط كبير، توسيط)، ثم add_text (فقرة تمهيدية، خط المتن).
3. add_page مع document_id فقط ← يرث ⁨A4⁩ عموديًا. يُرجِع page_number الجديد ويُعيد ضبط المؤشر.
4. add_text لعنوان القسم والمتن في الصفحة 2.
5. add_page مع orientation: "landscape" ← صفحة ⁨A4⁩ أفقية.
6. add_text للمحتوى العريض.
7. output_pdf ← ⁨base64.⁩

مثال برمجي — بيئة الإنتاج

تحقَّق من كل استجابة. بعد add_page، يبدأ المحتوى من أعلى الصفحة الجديدة. إعادة ضبط المؤشر سلوك مقصود، لا خلل. تتبَّع position.page في استجابات add_text لمعرفة متى ينساب المحتوى إلى صفحة لاحقة. استدعِ output_pdf مرةً واحدةً بالضبط، ثم تخلَّص من document_id.

الحالات الحدية والمزالق

• إعادة ضبط المؤشر. بعد add_page، يستقر المؤشر عند الهامش العلوي الأيسر للصفحة الجديدة. من الأخطاء الشائعة توقُّع أن يواصل من موضع الصفحة السابقة.
• document_id مطلوب. تتطلب كل أداة باستثناء create_pdf قيمة document_id. إغفالها خطأ.
• اتجاه غير صالح. القيمتان الصالحتان هما "portrait" و"landscape" فقط.
• التحرير بعد الإخراج. تفشل إضافة المحتوى بعد output_pdf مع destroy: true، لأن الجلسة لم تعد موجودة.

الأداء

يبقى المستند النصي متعدد الصفحات ضمن حد ميزانية الصفحات، ويكون حجم الناتج بضعة ⁨KB.⁩ الملف التعريفي structural: لا تثبت قيمة /ID في المُذيَّل ولا الطوابع الزمنية بين عمليات التشغيل.

ملاحظات أمنية

ليس لوضع ⁨base64⁩ أي آثار جانبية. يخضع إخراج الملف لبوابة؛ راجع قسم التدخل البشري في الحلقة (⁨HITL⁩). document_id مقبض مبهم. لا تشاركه بين طلبات متزامنة.

المطابقة

البيان	المواصفة	البند	⁨reference_id⁩
يُوصَل إلى الصفحات من خلال شجرة الصفحات.	⁨ISO 32000-2⁩	§7.7.3
يحدد كائن الصفحة سماته الهندسية الخاصة.	⁨ISO 32000-2⁩	§7.7.3.3

السياق التجاري

غير منطبق — جميع الأدوات من ⁨Core.⁩

توافر وسائل النقل

وسيلة النقل	متاحة	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم	استدعاء tools/call لكل أداة.
⁨REST⁩	نعم	عملية واحدة لكل أداة.
⁨gRPC⁩	نعم	استدعاء أحادي لكل أداة.

مستوى خطورة ⁨HITL⁩

create_pdf آمن؛ وadd_text وadd_page عند مستوى تنبيه؛ وoutput_pdf عند مستوى موافقة مطلوبة، ويُخفَّض إلى مراجعة في وضع ⁨base64.⁩ يظل إخراج الملف عند مستوى موافقة مطلوبة. راجع الموافقة على الإخراج ومستويات خطورة ⁨HITL⁩.

مغلف ⁨JSON⁩ لبوابة التأكيد

خرج ⁨base64⁩ في هذا المثال:

{ "allowed": true }

يعرض الموافقة على الإخراج نموذج التحدي.

انظر أيضًا

• مرحبًا بالعالم
• فحص التخطيط
• كتالوج الأدوات