EmbedFileA

文档属性

描述

末尾的 A 表示 ANSI（char）DLL 入口点，ActiveX/COM 接口仅公开 Unicode 形式。其行为与 EmbedFile 相同，字符串参数会按照当前的 SetAnsiMode 代码页进行解释

把外部文件嵌入 PDF，并注册为文档级附件。Acrobat 和其他阅读器会在附件侧栏中显示文档级附件。该调用相当于先调用 AddEmbeddedFile，再调用 AddToFileList：文件会作为 embedded file stream 保存，并在 Catalog 的 /Names /EmbeddedFiles name tree 中以提供的标题加入引用条目

PDF 版本行为：嵌入文件流和文件规范字典需要 PDF 1.3，而该便捷调用使用的文档级 /Names /EmbeddedFiles 名称树需要 PDF 1.4。当前文档版本较低且未锁定保存版本时，EmbedFile 会自动将文档提升至 PDF 1.4，记录 /EmbeddedFiles name tree，并将其写入 AutoBumpedFeatures。调用方锁定较低保存版本时，兼容性检查会以 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` name tree 中使用的键。必须在文档内唯一；如果同名文件已存在，调用会失败
FileName	磁盘上源文件的完整路径。该文件字节会复制到 PDF 中
MIMEType	标识文件内容的 MIME 类型，例如 `image/jpeg`、`text/csv`、`application/xml`。MIME 类型未知时传入空字符串；查看器会回退到文件扩展名

返回值

0	无法嵌入文件：源文件不存在、标题已被使用，或没有打开的文档
1	文件已嵌入并列入文档附件 name tree

备注

此调用只创建文档级附件。如果要在特定页面上绘制可点击的回形针注释并指向嵌入文件，请改用 AddEmbeddedFile 后接 AddFileAttachment（或 AddLinkToEmbeddedFile）

PDF/A 兼容性

PDF/A-1、PDF/A-2（SetPDFAMode 的模式 1–4）禁止任意嵌入文件。PDF/A guard 会在这些模式下阻止 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