Attachments
Attachments
本页介绍在 PDF 中嵌入文件的方法。有两种不同的机制：文档级附件，即嵌入文件但在任何页面上都没有可见的存在；以及页面锚定的文件附件注释，在特定页面上放置可点击的图标。
文档级附件
Document.AddAttachment() 将 bytes 嵌入到 name 下，并将其 upsert 到文档的嵌入文件名称树中——使用相同名称再次添加会覆盖现有条目。它返回一个 Attachment 句柄。Document.GetAttachments() 将每个文档级附件作为 Attachment 句柄数组返回，按名称排序，Document.RemoveAttachment() 则按名称删除一个。
该 Attachment 句柄将 Name、Description、MimeType、Size、CreationDate 和 ModDate 公开为属性，GetBytes() 用于读取嵌入文件的原始内容，GetField() / SetField() / RemoveField() 用于对单个 /Filespec 字段进行更底层的访问。传递给 AddAttachment() 的可选 AttachmentOptions 接受 mimeType、description、compress、creationDate 和 modDate。
在当前平台的知识快照中，尚未提供该 API 的经过验证的代码示例——请参阅下方的 API Reference 摘要，以获取确切的方法和属性名称。
页面锚定文件附件
Page.AddFileAttachment() 嵌入一个文件，并在特定页面的给定 rect 处放置一个 /FileAttachment 图标注释，返回一个 FileAttachmentAnnotation。与文档级附件不同，这种附件在 PDF 查看器中是可见且可点击的。FileAttachmentAnnotation 共享通用注释属性（Rect、Color、Contents、Name、Flags、Print、Hidden、Opacity），以及它自己的 Icon 和 FileName，并支持 GetBytes() 来读取嵌入的内容，以及 Flatten() 将其图标烘焙到静态页面内容中。
技巧与最佳实践
- 对于应随 PDF 一起携带但不出现在任何页面上的文件，使用文档级附件（
Document.AddAttachment()）；当文件应在特定位置以可点击图标的形式呈现时，使用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 句柄数组，按名称排序。
我如何读取附件的文件内容？
在 Attachment（或 FileAttachmentAnnotation）句柄上调用 GetBytes()——两者均可使用。
我可以删除附件吗？
是的——Document.RemoveAttachment(name) 按名称删除文档级别的附件，并返回是否找到了并删除了该附件。
API Reference 摘要
| 类/方法 | 描述 |
|---|---|
Document.AddAttachment() | 将字节嵌入为具名的文档级附件 |
Document.GetAttachments() | 列出所有文档级附件 |
Document.RemoveAttachment() | 按名称删除文档级附件 |
Attachment | 处理超过一个嵌入文件； Name, Description, MimeType, Size, GetBytes() |
Page.AddFileAttachment() | 将文件嵌入为页面锚定的可点击图标批注 |
FileAttachmentAnnotation | 页面锚定附件的注释句柄；添加 Icon，FileName |
