Attachments
Attachments
تغطي هذه الصفحة دمج الملفات داخل ملف PDF. هناك آليتان مميزتان: المرفقات على مستوى المستند، وهي ملفات مدمجة لا تظهر على أي صفحة، ومرفقات الملفات المربوطة بالصفحة، التي تضع أيقونة قابلة للنقر على صفحة معينة.
المرفقات على مستوى المستند
Document.AddAttachment() يدمج bytes تحت name، مُحدِّثًا إياه في شجرة أسماء الملفات المدمجة للمستند — إضافةً له مرة أخرى بنفس الاسم تستبدل الإدخال الموجود. يُعيد Attachment كمؤشر. Document.GetAttachments() تُعيد كل مرفق على مستوى المستند كمصفوفة من مؤشرات Attachment، مُرتَّبة حسب الاسم، وDocument.RemoveAttachment() تُزيل أحدها بالاسم.
يُظهر Attachment Name، Description، MimeType، Size، CreationDate، وModDate كخصائص، GetBytes() لقراءة المحتوى الخام للملف المدمج، وGetField() / SetField() / RemoveField() للوصول منخفض المستوى إلى حقول /Filespec الفردية. يَقبل AttachmentOptions الاختياري المُمرَّر إلى AddAttachment() mimeType، description، compress، creationDate، وmodDate.
لا يتوفر مثال شفرة مُتحقق منه لهذا API في لقطة المعرفة الحالية لهذا المنصّة — راجع ملخص API Reference أدناه للحصول على الطريقة الدقيقة وأسماء الخصائص.
مرفقات الملفات المربوطة بالصفحة
Page.AddFileAttachment() يضمّ ملفًا ويضع تعليقة أيقونة /FileAttachment في rect محدد على صفحة معينة، مع إرجاع FileAttachmentAnnotation. على عكس المرفق على مستوى المستند، هذا المرفق يكون مرئيًا وقابلًا للنقر في عارض PDF. FileAttachmentAnnotation يشارك خصائص التعليقات العامة (Rect, Color, Contents, Name, Flags, Print, Hidden, Opacity) بالإضافة إلى Icon وFileName الخاصة به، ويدعم GetBytes() لقراءة المحتوى المضمّن وFlatten() لتضمين الأيقونة في محتوى الصفحة الثابت.
نصائح وأفضل الممارسات
- استخدم مرفقًا على مستوى المستند (
Document.AddAttachment()) لملف يجب أن يرافق ملف PDF دون الظهور على أي صفحة؛ استخدمPage.AddFileAttachment()عندما ينبغي تمثيل الملف بأيقونة قابلة للنقر في موقع محدد. Document.AddAttachment()يستبدل مرفقًا موجودًا يحمل نفسname— تحقق منDocument.GetAttachments()أولاً إذا كنت تريد تجنّب استبداله عن غير قصد.- اقرأ محتوى المرفق مرةً أخرى باستخدام
GetBytes()على أي نوع من المقابض — الطريقة موجودة على كل منAttachmentوFileAttachmentAnnotation.
مشكلات شائعة
| مشكلة | السبب | الإصلاح |
|---|---|---|
| تم استبدال المرفق الذي تم إضافته حديثًا بآخر موجود | تم استدعاء Document.AddAttachment() باستخدام name مستخدم بالفعل | استدعِ Document.GetAttachments() أولاً للتحقق من حدوث تصادم في الأسماء |
| المرفق لا يحتوي على أيقونة مرئية على الصفحة | تم استخدام Document.AddAttachment()، وهو على مستوى المستند ولا يمتلك وجودًا على الصفحة حسب التصميم | استخدم Page.AddFileAttachment() بدلاً من ذلك لأيقونة مرئية ومثبتة على الصفحة |
Document.RemoveAttachment() يُعيد false | لا توجد مرفق بالـ name المحدد في شجرة الأسماء | تأكد من الاسم الدقيق عبر Document.GetAttachments() قبل الإزالة |
FAQ
ما الفرق بين Document.AddAttachment و Page.AddFileAttachment؟
Document.AddAttachment() يضم ملفًا في المستند دون أيقونة مرئية على أي صفحة. Page.AddFileAttachment() يضم ملفًا ويضع توضيح أيقونة /FileAttachment قابلة للنقر في موقع محدد على صفحة واحدة.
كيف يمكنني سرد جميع المرفقات المضمّنة بالفعل في مستند؟
استدعِ Document.GetAttachments()، الذي يُرجع جميع المرفقات في المستند كمصفوفة من مقابض Attachment مرتبة حسب الاسم.
كيف يمكنني قراءة محتوى ملف المرفق وإرجاعه؟
استدعِ GetBytes() على مقبض Attachment (أو FileAttachmentAnnotation) — وهو متاح في كليهما.
هل يمكنني إزالة مرفق؟
نعم — Document.RemoveAttachment(name) يزيل مرفقًا في المستند بالاسم ويعيد ما إذا تم العثور عليه وإزالته.
API Reference ملخص
| فئة/طريقة | وصف |
|---|---|
Document.AddAttachment() | ضمّن البايتات كمرفق مسمى على مستوى المستند |
Document.GetAttachments() | قائمة جميع المرفقات على مستوى المستند |
Document.RemoveAttachment() | إزالة مرفق على مستوى المستند بالاسم |
Attachment | التعامل مع ملف مضمّن واحد أو أكثر؛ Name, Description, MimeType, Size, GetBytes() |
Page.AddFileAttachment() | تضمين ملف كتعليق أيقونة قابل للنقر ومُثبت على الصفحة |
FileAttachmentAnnotation | مقبض تعليق المرفق المثبت على الصفحة؛ يضيف Icon, FileName |
