如何使用 GroupDocs.Watermark Java 為 Excel 添加附件

簡介

在當今快速變化的商業環境中，add attachment to excel 是一種強大的方式，可將相關文件集中在一起，而不會使檔案系統變得雜亂。無論您是需要將合約 PDF 與財務模型捆綁，或是將圖像附加到專案追蹤器，將檔案直接嵌入 Excel 工作表都能簡化協作並提升資料完整性。本教學將一步步示範如何使用 GroupDocs.Watermark for Java 來快速且可靠地 add attachment to excel 工作表。

快速解答

  • 什麼程式庫可為 Excel 添加附件？ GroupDocs.Watermark for Java.
  • 需要多少行程式碼？ 只需在載入工作簿後寫兩行程式碼。
  • 我可以附加任何檔案類型嗎？ 可以 — PDF、圖片、Word 文件等（超過 50 種格式）。
  • 測試是否需要授權？ 免費的臨時授權即可滿足評估需求。
  • 記憶體使用是否成問題？ API 以串流方式處理資料，即使是 500 頁的工作簿也能保持在 200 MB 記憶體以下。

什麼是 add attachment to excel？

Add attachment to excel 指的是將外部檔案嵌入 Excel 工作表，使使用者能直接從試算表開啟該檔案。此功能將相關文件與其描述的資料一起保存，免除額外的檔案傳輸需求。

為何使用 GroupDocs.Watermark for Java 來嵌入檔案？

GroupDocs.Watermark 支援 30+ 輸入與輸出格式，可在不將整個檔案載入記憶體的情況下處理多百頁的試算表，並提供只需少量方法呼叫的簡易 API。使用此程式庫可將手動 zip 檔案處理降低至最高 80 %，同時消除檔案搬移時連結斷裂的風險。

前置條件

要跟隨本教學，您需要：

  • Java Development Kit (JDK) 8+ – GroupDocs.Watermark 支援的最低版本。
  • GroupDocs.Watermark for Java 24.11 – 撰寫時的最新穩定版本。
  • IDE – IntelliJ IDEA、Eclipse 或任何相容 Maven 的環境。

必要的函式庫與相依性

使用 Maven 或直接下載 JAR 檔案將 GroupDocs.Watermark 整合至您的專案。以下示範如何以 Maven 設定：

<repositories>
   <repository>
      <id>repository.groupdocs.com</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/watermark/java/</url>
   </repository>
</repositories>

<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-watermark</artifactId>
      <version>24.11</version>
   </dependency>
</dependencies>

直接下載
或者，從 GroupDocs.Watermark for Java releases 下載最新版本。

取得授權

先透過從 此處 下載臨時授權，以免費試用完整功能，無任何限制。若要正式上線，請購買永久授權。

設定 GroupDocs.Watermark for Java

Watermarker 類別是 GroupDocs.Watermark 中所有文件操作的入口。加入 Maven 相依性後，您可以使用 Excel 檔案路徑與可選的載入選項來實例化 Watermarker。

import com.groupdocs.watermark.Watermarker;

public class SetupGroupDocs {
    public static void main(String[] args) throws Exception {
        // Initialize watermarker with an input file
        Watermarker watermarker = new Watermarker("path/to/your/spreadsheet.xlsx");
        
        // Your code to manipulate the document goes here
        
        // Close the watermarker when done
        watermarker.close();
    }
}

此初始化會讓程式庫準備好讀取、修改與儲存試算表內容。

實作指南

本節將逐步說明 add attachment to excel 工作表所需的每個步驟。

載入 Excel 試算表

如何載入 Excel 工作簿？
建立 Watermarker 實例，傳入 Excel 檔案路徑以及 SpreadsheetLoadOptions 物件，告訴 API 將檔案視為試算表。此步驟以讀寫模式開啟工作簿，同時保持低記憶體使用量。

import com.groupdocs.watermark.options.SpreadsheetLoadOptions;

public class LoadSpreadsheet {
    public static void run() throws Exception {
        // Create new SpreadsheetLoadOptions instance
        SpreadsheetLoadOptions loadOptions = new SpreadsheetLoadOptions();
        
        // Initialize Watermarker with the Excel file path and load options
        Watermarker watermarker = new Watermarker("YOUR_DOCUMENT_DIRECTORY/spreadsheet.xlsx", loadOptions);
    }
}

讀取檔案為位元組

準備檔案作為附件的最佳方式是什麼？
使用 Java 的 Files.readAllBytes 方法將外部檔案（PDF、圖片、DOCX 等）讀取為位元組陣列。產生的位元組陣列可直接傳遞給附件 API，確保原始檔案格式得以保留。

import java.io.File;
import java.io.FileInputStream;
import java.io.InputStream;

public class ReadFileToBytes {
    public static byte[] readFileToByteArray(String filePath) throws Exception {
        File file = new File(filePath);
        byte[] fileContentBytes = new byte[(int) file.length()];

        try (InputStream inputStream = new FileInputStream(file)) {
            inputStream.read(fileContentBytes);
        }
        
        return fileContentBytes;
    }
}

為試算表工作表添加附件

如何在特定工作表中嵌入檔案？
呼叫 watermarker.getWorksheets().get(0).addAttachment("AttachmentName.ext", fileBytes)。第一個參數是顯示於 Excel「附件」窗格的名稱，第二個參數是前一步取得的位元組陣列。附件會成為工作表內部封裝的一部份。

addAttachment 會將指定檔案作為附件嵌入工作表。

import com.groupdocs.watermark.contents.SpreadsheetContent;
import com.groupdocs.watermark.contents.SpreadsheetWorksheet;

public class AddAttachmentToWorksheet {
    public static void run(Watermarker watermarker, byte[] attachmentBytes, String fileName, byte[] previewImageBytes) throws Exception {
        SpreadsheetContent content = watermarker.getContent(SpreadsheetContent.class);
        SpreadsheetWorksheet worksheet = content.getWorksheets().get_Item(0);

        worksheet.getAttachments().addAttachment(
            attachmentBytes,
            fileName,
            previewImageBytes,
            50, 100, 200, 400
        );
    }
}

儲存試算表變更

如何儲存已修改的工作簿？
呼叫 watermarker.save("output.xlsx", SaveFormat.Xlsx)。API 會將更新後的封裝（包括新附件）寫入指定路徑。所有變更於一次操作中完成，確保流程快速且具原子性。

save 會將已修改的工作簿（含附件）寫入指定檔案。

public class SaveSpreadsheet {
    public static void run(Watermarker watermarker, String outputPath) throws Exception {
        watermarker.save("YOUR_OUTPUT_DIRECTORY/modified_spreadsheet.xlsx");
        watermarker.close();
    }
}

實務應用

在 Excel 工作簿中嵌入檔案可解決許多實務問題：

  • **法律文件：**將已簽署的合約與財務表格一起存放，確保稽核人員能即時取得原始協議。
  • **報告與簡報：**將支援的 PDF 或投影片檔案附加至資料驅動的報告，讓利害關係人一次取得所有相關資料。
  • **教育內容：**教師可將練習冊與參考 PDF 捆綁，簡化向學生的分發。

效能考量

在 add attachment to excel 時優化效能相當直接：

  • **記憶體管理：**始終呼叫 watermarker.close()（或使用 try‑with‑resources 區塊）以即時釋放檔案句柄。
  • **批次處理：**處理數十本工作簿時，將其分成 10–20 本一批，以避免過度的堆積記憶體使用。
  • **大型附件：**對於超過 50 MB 的檔案，建議分塊串流位元組陣列，以降低 JVM 記憶體佔用。

常見問題

Q: 我可以在同一工作表附加多個檔案嗎？
A: 可以。重複呼叫 addAttachment，使用不同的檔名與位元組陣列；每次呼叫都會在工作表的附件集合中建立一個獨立條目。

Q: 附件會在 Excel 介面中顯示嗎？
A: 絕對會。Excel 會在「插入 → 物件 → 從檔案建立 → 顯示為圖示」窗格中顯示附件，使用者可雙擊圖示開啟嵌入的文件。

Q: 這能在受密碼保護的 Excel 檔案上使用嗎？
A: 只要在 SpreadsheetLoadOptions.setPassword("yourPassword") 中提供密碼，GroupDocs.Watermark 即可開啟受密碼保護的工作簿。

Q: 附件有大小限制嗎？
A: 此程式庫支援最高 2 GB 的附件，唯一限制為底層 ZIP 封裝格式與可用磁碟空間。

Q: 之後如何移除附件？
A: 取得工作表的附件集合，然後在再次儲存工作簿前呼叫 removeAttachment("AttachmentName.ext") 即可。

結論

您現在已掌握如何使用 GroupDocs.Watermark for Java add attachment to excel。透過載入工作簿、將外部檔案轉為位元組陣列、以單一 API 呼叫嵌入，並儲存結果，即可將所有相關文件整合於乾淨且可搜尋的套件中。可嘗試不同檔案類型、自動化批次處理，並探索其他浮水印功能，以進一步豐富您的試算表。

最後更新： 2026-06-06
測試環境： GroupDocs.Watermark 24.11 for Java
作者： GroupDocs

相關教學