Attachments
Attachments
このページでは、PDF 内にファイルを埋め込む方法について説明します。主に 2 つのメカニズムがあります。ドキュメントレベルの添付ファイルは、ページ上に目に見える形跡を残さずに埋め込まれるファイルで、ページアンカーファイル添付アノテーションは、特定のページにクリック可能なアイコンを配置します。
ドキュメントレベルの添付ファイル
Document.AddAttachment() は bytes を name の下に埋め込み、ドキュメントの埋め込みファイル名ツリーにアップサートします — 同じ名前で再度追加すると既存のエントリが上書きされます。Attachment ハンドルを返します。Document.GetAttachments() は、名前でソートされた Attachment ハンドルの配列としてすべてのドキュメントレベルの添付ファイルを返し、Document.RemoveAttachment() は名前で1つを削除します。
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アイコンアノテーションを配置します。
ドキュメントにすでに埋め込まれているすべての添付ファイルを一覧表示するにはどうすればよいですか？
名前順にソートされたAttachmentハンドルの配列として、すべてのドキュメントレベル添付ファイルを返すDocument.GetAttachments()を呼び出します。
添付ファイルの内容を読み出すにはどうすればよいですか？
Attachment（またはFileAttachmentAnnotation）ハンドルに対してGetBytes()を呼び出します—どちらでも利用可能です。
添付ファイルを削除できますか？
はい—Document.RemoveAttachment(name)は名前でドキュメントレベルの添付ファイルを削除し、見つかって削除されたかどうかを返します。
API Reference の概要
| クラス/メソッド | 説明 |
|---|---|
Document.AddAttachment() | バイト列を名前付きのドキュメントレベル添付として埋め込みます |
Document.GetAttachments() | ドキュメントレベルの添付ファイルをすべて一覧表示する |
Document.RemoveAttachment() | 名前でドキュメントレベルの添付ファイルを削除する |
Attachment | 1つ以上の埋め込みファイルを処理する; Name, Description, MimeType, Size, GetBytes() |
Page.AddFileAttachment() | ファイルをページに固定されたクリック可能なアイコン注釈として埋め込む |
FileAttachmentAnnotation | ページにアンカーされた添付ファイルの注釈ハンドル; Icon と FileName を追加します。 |
