使用 GroupDocs.Merger for Java 添加 PDF 附件

將外部檔案（例如 PowerPoint 簡報）直接嵌入 PDF，是將相關內容集中管理的強大方法。在本教學中，您將使用 GroupDocs.Merger for Java 添加 PDF 附件 到現有的 PDF，學習如何 轉換 pptx PDF 附件，並探索保存與管理產生文件的最佳實踐。

快速解答

  • 「add pdf attachment」是什麼意思？ 它會將另一個檔案（例如 PPTX）作為附件嵌入 PDF 中。
  • 哪個函式庫支援此功能？ GroupDocs.Merger for Java 提供簡易的 PDF 附件 API。
  • 我需要授權嗎？ 免費試用可用於評估；正式環境需購買永久授權。
  • 可以嵌入其他格式嗎？ 可以，支援大多數常見文件類型。
  • 它是執行緒安全的嗎？ 當每個執行緒使用各自的 Merger 實例時，操作是安全的。

「add pdf attachment」是什麼？

將 PDF 附件加入指的是把外部檔案插入 PDF 容器，讓使用者可直接從 PDF 檢視器的附件面板開啟該檔案。這樣可將所有相關資產集中於單一可攜帶的檔案中。

為什麼使用 GroupDocs.Merger for Java？

  • 簡易 API – 單行呼叫即可嵌入或抽取檔案。
  • 跨平台 – 支援 Windows、Linux 與 macOS。
  • 效能導向 – 能有效處理大型檔案。
  • 可擴充 – 可與其他 GroupDocs 模組結合，實現完整文件工作流程。

前置條件

  • Java 8 或更新版本（IntelliJ IDEA、Eclipse，或任何您偏好的 IDE）。
  • Maven 或 Gradle 用於相依管理。
  • GroupDocs.Merger for Java 21.x 或更新版本。

設定 GroupDocs.Merger for Java

安裝資訊

將 GroupDocs.Merger 相依加入您的專案。

Maven:

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-merger</artifactId>
    <version>21.x.x</version>
</dependency>

Gradle:

implementation 'com.groupdocs:groupdocs-merger:21.x.x'

您可以從 GroupDocs.Merger for Java releases 下載最新的二進位檔。

取得授權

  • 免費試用 – 完整功能且無時間限制。
  • 臨時授權 – 申請短期金鑰以進行測試。
  • 購買 – 在 GroupDocs Purchase 取得永久授權。

基本初始化

建立一個以來源 PDF 路徑為參數的 Merger 實例。此步驟為 add pdf attachment 操作做好準備。

如何使用 GroupDocs.Merger 為 PDF 添加 pdf 附件

以下為逐步說明，涵蓋路徑定義、選項設定、文件嵌入，最後 save pdf embedded document。

步驟 1：定義檔案路徑與選項

使用 Java 的 Paths API 可確保跨作業系統的路徑處理。

import java.nio.file.Paths;

String documentDirectory = "YOUR_DOCUMENT_DIRECTORY";
String outputDirectory = "YOUR_OUTPUT_DIRECTORY";

// Construct full path for the source PDF file
String pdfFilePath = Paths.get(documentDirectory, "SAMPLE_PDF").toString();

// Construct full path for the embedded PPTX document
String embeddedDocumentPath = Paths.get(documentDirectory, "SAMPLE_PPTX").toString();

步驟 2：設定嵌入選項

建立 PdfAttachmentOptions 物件，以告訴 merger 要附加哪個檔案。

import com.groupdocs.merger.domain.options.PdfAttachmentOptions;

// Set up attachment options for the embedded document
PdfAttachmentOptions attachmentOptions = new PdfAttachmentOptions(embeddedDocumentPath);

步驟 3：初始化 Merger 並嵌入文件

以來源 PDF 建立 Merger 實例，並呼叫 importDocument 以嵌入 PPTX。

import com.groupdocs.merger.Merger;

// Create a Merger instance for the source PDF
Merger merger = new Merger(pdfFilePath);

// Import the embedded document into the PDF using specified options
merger.importDocument(attachmentOptions);

步驟 4：儲存結果

產生清晰的輸出檔名，並將 save pdf embedded document 儲存至目標資料夾。

String pdfFileName = Paths.get(pdfFilePath).getFileName().toString();
String outputFilePath = Paths.get(outputDirectory, "ImportDocumentToPdf-" + pdfFileName.replaceFirst("\\.pdf", ".pdf-Embedded")).toString();

// Save the resultant PDF to the specified path
merger.save(outputFilePath);

小技巧： 確認輸出檔案出現在 PDF 檢視器的附件面板中，以驗證 add pdf attachment 是否成功。

處理檔案路徑與輸出目錄

健全的路徑處理可協助您在批次程序中 create pdf embedded files：

  1. 動態路徑建構 – 可在 Windows、macOS 與 Linux 上運作。
  2. 自動命名 – 保留原始檔名，並在其後加上 “‑Embedded” 以便辨識。

實務應用

  • 會議資料包 – 將投影片、試算表或合約嵌入單一 PDF 以供分發。
  • 法規提交 – 將輔助文件與主報告合併，以符合合規標準。
  • 自動化報告 – 產生包含原始資料檔案作為附件的 PDF，以作稽核追蹤。

效能考量

  • 保持嵌入檔案大小適中，以避免過長的處理時間。
  • 儲存完成後釋放 Merger 實例（merger.close()），以釋放記憶體。
  • 對於大量操作，將每個嵌入任務放在獨立執行緒中，以利用多核心 CPU。

常見問題與解決方案

問題原因解決方案
找不到檔案路徑不正確或缺少檔案權限再次確認 documentDirectory 並確保應用程式具有讀寫權限。
OutOfMemoryError附件過大增加 JVM 堆積大小（-Xmx）或嵌入較小版本的檔案。
附件未顯示檢視器快取舊版本在全新檢視器實例中開啟 PDF，或清除快取。

常見問答

Q: 我可以使用 GroupDocs.Merger 嵌入非 PPTX 檔案嗎？
A: 可以，API 支援多種格式（DOCX、XLSX、圖片等）用於 add pdf attachment 操作。

Q: 嵌入檔案的最大尺寸是多少？
A: 取決於伺服器記憶體與 JVM 堆積大小；較大的檔案可能需要更高的記憶體配置。

Q: 如何處理嵌入過程中的例外情況？
A: 將程式碼包在 try‑catch 區塊中，捕捉 IOException 或 GroupDocsMergerException，以記錄並優雅地恢復。

Q: 之後可以移除附件嗎？
A: 目前 GroupDocs.Merger 主要支援添加附件；若要移除需透過另行的抽取與重新建立流程。

Q: 我可以在雲原生 Java 應用程式中使用嗎？
A: 當然可以——只要加入 Maven/Gradle 相依，並確保執行環境能存取所需檔案。

資源

最後更新： 2026-02-13
測試環境： GroupDocs.Merger 21.x.x for Java
作者： GroupDocs