تضمين الصور باستخدام NextPDF Connect

لمحة سريعة

ضمِّن صورة في ملف ⁨PDF⁩ باستخدام ⁨NextPDF Connect.⁩ استخدم للمصدر إما مسار ملف يستطيع الخادم قراءته أو معرّف موارد منتظم (⁨URI⁩) للبيانات يتضمن ⁨base64.⁩ تستخدم هذه العملية create_pdf وadd_image وoutput_pdf — وهي كلها أدوات ⁨Core.⁩ يرسم ⁨NextPDF⁩ الصورة بوصفها كائن ⁨XObject⁩ صوريًا يرسمه عامل التشغيل Do (⁨ISO 32000-2⁩ §8.9).

التثبيت

composer require nextpdf/server

اربط ناقلًا. يدعم ⁨NextPDF⁩ تنسيقات الصور النقطية: ⁨PNG⁩ و⁨JPEG⁩ و⁨GIF.⁩

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

تأخذ add_image المدخل source وتحلّه وفق هذا الترتيب الثابت:

معرّف موارد منتظم (⁨URI⁩) للبيانات — سلسلة نصية تبدأ بـ data:. يفك ⁨NextPDF⁩ ترميز نوع ⁨MIME⁩ وحمولة ⁨base64⁩ إلى ملف مؤقت، ويضمِّنه، ثم يحذف الملف المؤقت.
⁨base64⁩ خام — يفك ⁨NextPDF⁩ ترميز سلسلة ⁨base64⁩ طويلة ويتعامل معها على أنها ⁨PNG.⁩
مسار ملف — يتعامل ⁨NextPDF⁩ مع أي شيء آخر على أنه مسار في نظام الملفات يجب أن تستطيع عملية الخادم قراءته.

تُوضع الصورة عند x/y، بوحدات المستخدم (المليمترات افتراضياً). مرِّر width فقط ليحسب ⁨NextPDF⁩ الارتفاع ويحافظ على نسبة العرض إلى الارتفاع. مرِّر width وheight معاً ليضبط ⁨NextPDF⁩ مقاس الصورة على تلك الأبعاد بالضبط. الكائن المضمَّن هو كائن خارجي يُرسم ضمن محتوى الصفحة (⁨ISO 32000-2⁩ §8.8).

واجهة ⁨API⁩

الأداة	الدور	مستوى الخطورة
`create_pdf`	فتح جلسة	آمنة
`add_image`	تضمين صورة من مسار أو من معرّف موارد منتظم (⁨URI⁩) للبيانات	تحذير
`output_pdf`	تصيير ملف ⁨PDF⁩ وإرجاعه	موافقة مطلوبة / مراجعة (⁨base64⁩)

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

مثال الكود — البدء السريع

create_pdf (⁨A4⁩ باتجاه طولي، مع عنوان) ← document_id.
add_image مع تعيين source إلى مسار مطلق، وتمرير x وy وwidth.
add_image مع تعيين source إلى معرّف موارد منتظم (⁨URI⁩) للبيانات من نوع data:image/png;base64,...، مع width وheight صريحين.
output_pdf ← ⁨base64.⁩

مثال الكود — بيئة الإنتاج

استخدم معرّف موارد منتظم (⁨URI⁩) للبيانات لصورة يولّدها المضيف في الذاكرة، مثل تصيير مخطط أو لقطة شاشة. استخدم مسار ملف لأصل موجود مسبقاً على الخادم. استخدم المسارات المطلقة دائماً. يُحلّ المسار النسبي بالنسبة إلى دليل العمل الخاص بـالخادم، وغالباً لا يكون هذا دليل المضيف. قبل المتابعة، تأكَّد من أن استجابة add_image تُشير إلى أن الصورة وُضعت في الصفحة المتوقَّعة.

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

المسار غير موجود. يؤدي مسار ملف غير موجود إلى إرجاع خطأ عدم العثور على الصورة.
تنسيق غير مدعوم. يرفض ⁨NextPDF⁩ صيغ ⁨SVG⁩ و⁨BMP⁩ و⁨WebP.⁩ حوِّل الصورة أولاً.
⁨base64⁩ / معرّف موارد منتظم (⁨URI⁩) للبيانات مشوَّه. تؤدي الحمولة التالفة، أو افتقار معرّف موارد منتظم (⁨URI⁩) للبيانات إلى فاصل الفاصلة، إلى إرجاع خطأ في فك الترميز.
صورة بحجم مفرط. تُقتطع الصورة التي تتجاوز حجم الصفحة عند الحافة ولا تُرفض. احسب width/height بالنسبة إلى الصفحة بعد طرح هوامشها (⁨A4⁩ طولي هو 210×297 ⁨mm⁩).

الأداء

يتناسب حجم المُخرَج مع محتوى الصورة. غالباً ما يكون حجم صورتين صغيرتين 10–50 ⁨KB.⁩ ميزانية تضمين الصور أوسع من ميزانية النص وحده. تستخدم هذه الصفحة ملف التعريف structural.

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

يقرأ وضع مسار الملف من نظام ملفات الخادم بامتيازات عملية الخادم. قيِّد المسارات التي يُسمح للمضيف بتمريرها. لا تدع المستدعين غير الموثوقين يوجِّهون source إلى ملفات اعتباطية على الخادم. يحمل وضع ⁨base64⁩ البايتات مضمَّنة، لذلك يتجنّب كشف مسارات الخادم.

المطابقة

العبارة	المواصفة	البند	⁨reference_id⁩
الصورة هي كائن ⁨XObject⁩ صوري يرسمه `Do`.	⁨ISO 32000-2⁩	§8.9
الصور كائنات خارجية تُرسم في محتوى الصفحة.	⁨ISO 32000-2⁩	§8.8

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

غير منطبق — كل الأدوات مُضمَّنة في ⁨Core.⁩

توفر الناقل

الناقل	متاح	ملاحظات
⁨MCP⁩ (⁨stdio⁩)	نعم	تزيد حمولات ⁨base64⁩ الكبيرة حجم إطار ⁨stdio.⁩
⁨REST⁩	نعم	يُفضَّل استخدام ⁨multipart⁩ أو مسار خادم للأصول كبيرة الحجم.
⁨gRPC⁩	نعم	أحادي؛ وتنطبق حدود حجم الرسالة على ⁨base64⁩ المضمَّن.

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

create_pdf آمنة، وadd_image تحذير، وoutput_pdf موافقة مطلوبة — ويُخفَّض إلى مراجعة في وضع ⁨base64.⁩ تتم قراءة وضع المسار من جانب الخادم ولا تمر عبر بوابة منفصلة، لذا قيِّدها في طبقة السياسة (مستويات خطورة ⁨HITL⁩).

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

بالنسبة إلى مُخرَج ⁨base64⁩ هنا:

{ "allowed": true }