EmbedFile

خصائص المستند

الوصف

يضمّن ملفًا خارجيًا داخل PDF ويسجله كمرفق على مستوى المستند. ويعرض Acrobat وقارئات أخرى المرفقات على مستوى المستند في اللوحة الجانبية للمرفقات. وهذا الاستدعاء اختصار لـ AddEmbeddedFile يليه AddToFileList: يُخزَّن الملف كتدفق ملف مضمّن، ويُضاف مدخل يشير إليه إلى شجرة الأسماء /Names /EmbeddedFiles في الكتالوج تحت العنوان المزود

سلوك إصدار PDF: تتطلب تدفقات الملفات المضمّنة وقواميس مواصفة الملف إصدار PDF 1.3، بينما تتطلب شجرة الأسماء /Names /EmbeddedFiles على مستوى المستند التي يستخدمها هذا الاستدعاء الميسر إصدار PDF 1.4. إذا كان إصدار المستند الحالي أقل ولم يكن إصدار الحفظ مقفلًا، يرفع EmbedFile المستند تلقائيًا إلى PDF 1.4 ويسجل /EmbeddedFiles name tree في AutoBumpedFeatures. وإذا قفل المستدعي إصدار حفظ أقل، فترفض بوابة التوافق الحفظ مع LastErrorCode 602

الصيغة

Delphi

Function TPDFlib.EmbedFile(Const Title, FileName, MIMEType: WideString): Integer;

ActiveX

Function PDFlib::EmbedFile(Title As String, FileName As String, MIMEType As String) As Long

DLL

int DLEmbedFile(int InstanceID, const wchar_t * Title, const wchar_t * FileName, const wchar_t * MIMEType);

المعاملات

Title	الاسم المعروض في لوحة مرفقات القارئ والمستخدم كمفتاح في شجرة الأسماء `/EmbeddedFiles`. يجب أن يكون فريدًا داخل المستند؛ وإذا وُجد ملف بهذا العنوان سلفًا يفشل الاستدعاء
FileName	المسار الكامل لملف المصدر على القرص. وتُنسخ بايتات هذا الملف إلى PDF
MIMEType	نوع MIME الذي يحدد محتوى الملف (مثل `image/jpeg`، و`text/csv`، و`application/xml`). مرر سلسلة فارغة عندما يكون نوع MIME غير معروف؛ وسيستخدم العارضون امتداد الملف كبديل

قيم الإرجاع

0	تعذّر تضمين الملف — ملف المصدر مفقود أو العنوان مستخدم سلفًا أو لا يوجد مستند مفتوح
1	تم تضمين الملف وإدراجه في شجرة أسماء مرفقات المستند

ملاحظات

ينشئ هذا الاستدعاء مرفقًا على مستوى المستند فقط. لرسم تعليق توضيحي بأيقونة مشبك ورق قابلة للنقر على صفحة معينة يشير إلى الملف المضمّن، استخدم بدلًا من ذلك AddEmbeddedFile يليه AddFileAttachment‏ (أو AddLinkToEmbeddedFile)

توافق PDF/A:

PDF/A-1‏ وPDF/A-2‏ (الأوضاع 1–4 من SetPDFAMode) تحظر الملفات المضمّنة العشوائية. وتمنع حماية PDF/A استدعاء EmbedFile في تلك الأوضاع.
PDF/A-3‏ (الأوضاع 5 و6 و7) يسمح بالملفات المضمّنة من أي نوع MIME. ويتطلب ISO 19005-3 أيضًا أن يصرّح كل ملف مضمّن بعلاقته بالمستند عبر مفتاح AFRelationship — اضبطه صراحةً باستخدام SetEmbeddedFileAFRelationship.

عندما يكون SetPDFUAMode نشطًا تكتب المكتبة AFRelationship=Unspecified تلقائيًا لأي ملف مضمّن بلا علاقة صريحة؛ وتجاوزها بـ SetEmbeddedFileAFRelationship استيفاءً لـ ISO 14289-1 §7.11

مثال

// Embed a CSV of the source data as a document attachment
PDF.NewDocument;
PDF.AddStandardFont('Helvetica');
PDF.AddPage;
PDF.PrintText(50, 750, 'Sales summary, Q1 2026');

if PDF.EmbedFile('Source data — sales-Q1.csv', 'C:\reports\sales-Q1.csv', 'text/csv') = 1 then
  WriteLn('Attachment added')
else
  WriteLn('Failed to embed file');

PDF.SaveToFile('Q1-Summary.pdf');

انظر أيضا

AddEmbeddedFile, AddFileAttachment, AddLinkToEmbeddedFile, SetEmbeddedFileAFRelationship, EmbeddedFileCount, SetPDFAMode