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`

См. также:

Aspose.PDF — Enterprise Documentation