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 در snapshot دانش فعلی برای این پلتفرم موجود نیست — برای روش دقیق و نام‌های ویژگی‌ها، خلاصهٔ 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 را اضافه می‌کند |
