EmbedFileA

文件屬性

描述

結尾的 A 表示 ANSI（char）DLL 進入點，ActiveX/COM 介面僅公開 Unicode 形式。其行為與 EmbedFile 相同，字串引數會依據目前的 SetAnsiMode 字碼頁進行解譯

把外部檔案內嵌進 PDF 並登錄為文件層級附件。Acrobat 與其他閱讀器會在 Attachments 側邊面板顯示文件層級附件。此呼叫是 AddEmbeddedFile 加 AddToFileList 的簡寫：檔案以內嵌檔案串流儲存，並以提供的標題在目錄的 /Names /EmbeddedFiles 名稱樹加入一個參照它的條目。

PDF 版本行為：內嵌檔案串流與檔案規格字典需要 PDF 1.3；這個便捷呼叫使用的文件層級 /Names /EmbeddedFiles 名稱樹則需要 PDF 1.4。目前文件版本較低且儲存版本未鎖定時，EmbedFile 會自動把文件提升到 PDF 1.4，並在 AutoBumpedFeatures 記下 /EmbeddedFiles name tree；呼叫端鎖定了較低的儲存版本時，相容性閘門會以 LastErrorCode 602 拒絕儲存。

語法

Delphi

Function DLEmbedFileA(InstanceID: Integer; Title, FileName, MIMEType: PAnsiChar): Integer;

DLL

int DLEmbedFileA(int InstanceID, const char * Title, const char * FileName, const char * MIMEType);

參數

Title	閱讀器附件面板顯示的顯示名稱，也是 /EmbeddedFiles 名稱樹中的鍵。文件內必須唯一；已有同名檔案時呼叫會失敗。
FileName	磁碟上來源檔案的完整路徑。此檔案的位元組會複製進 PDF。
MIMEType	識別檔案內容的 MIME 類型（例如 `image/jpeg`、`text/csv`、`application/xml`）。若 MIME 類型未知，請傳入空字串；檢視器會退回使用副檔名

傳回值

0	無法內嵌檔案 — 來源檔不存在、標題已被使用，或未開啟任何文件。
1	檔案已內嵌，並列在文件附件名稱樹中。

備註

此呼叫只建立文件層級附件。想在特定頁面上畫出指向內嵌檔案、可點擊的迴紋針註解，請改用 AddEmbeddedFile 之後接 AddFileAttachment（或 AddLinkToEmbeddedFile）。

PDF/A compatibility:

PDF/A-1 與 PDF/A-2（SetPDFAMode 模式 1–4）禁止任意內嵌檔案。PDF/A 防護會在這些模式下封鎖 EmbedFile。
PDF/A-3（模式 5、6 與 7）允許任何 MIME 類型的內嵌檔案。ISO 19005-3 還要求每個內嵌檔案透過 AFRelationship 金鑰宣告其與文件的關聯 — 請用 SetEmbeddedFileAFRelationship 明確設定。

當 SetPDFUAMode 啟用時，程式庫會對任何沒有明確關聯的內嵌檔案自動寫入 AFRelationship=Unspecified；要滿足 ISO 14289-1 §7.11，可用 SetEmbeddedFileAFRelationship 覆寫。

範例

// Embed a CSV of the source data as a document attachment
PDF.NewDocument;
PDF.AddStandardFont('Helvetica');
PDF.AddPage;
PDF.PrintText(50, 750, 'Sales summary, Q1 2026');

if PDF.EmbedFile('Source data — sales-Q1.csv', 'C:\reports\sales-Q1.csv', 'text/csv') = 1 then
  WriteLn('Attachment added')
else
  WriteLn('Failed to embed file');

PDF.SaveToFile('Q1-Summary.pdf');

另見

AddEmbeddedFile, AddFileAttachment, AddLinkToEmbeddedFile, SetEmbeddedFileAFRelationship, EmbeddedFileCount, SetPDFAMode