在 Java 中使用 GroupDocs.Watermark 添加圖片水印：完整指南

在 Java 中添加圖片水印是保護品牌形象與確保文件真偽的常見需求。在本教學中，您將學會如何使用 GroupDocs.Watermark 函式庫 add image watermark java，涵蓋從載入圖片檔案、搜尋現有水印到以新圖形取代的全部步驟。完成後，您將擁有一套可於 PDF、Word 檔案以及基於圖片的文件中重複使用的模式。

快速答覆

  • 哪個函式庫負責在 Java 中處理圖片水印？ GroupDocs.Watermark for Java.
  • 我在正式環境使用需要授權嗎？ 是的，商業授權會移除試用限制。
  • 我可以處理 PDF 與 Office 檔案嗎？ 可以，API 支援超過 30 種格式。
  • 需要哪個 Java 版本？ JDK 8 或更新版本。
  • 唯一的加入相依方式是 Maven 嗎？ 建議使用 Maven，但也可以手動下載 JAR。

什麼是 add image watermark java？

add image watermark java 指的是使用 Java 程式碼將點陣圖（PNG、JPEG、BMP 等）嵌入文件的過程。此技術可在不改變原始內容版面的情況下，覆蓋商標、版權聲明或安全印章。

為什麼要在 Java 中使用 GroupDocs.Watermark？

GroupDocs.Watermark 支援 30 多種輸入與輸出格式——包括 PDF、DOCX、XLSX、PPTX 以及常見的圖片類型——同時在處理上百頁的檔案時不需將整個文件載入記憶體。函式庫的雜湊搜尋引擎可以 > 95% 的準確度定位水印，將掃描大型檔案的時間縮短最多 70%。

先決條件

  • Java Development Kit (JDK)： 已安裝 8 版或以上。
  • GroupDocs.Watermark for Java： 版本 24.11（本指南使用的版本）。
  • Maven： 用於相依管理，亦可手動下載 JAR。

如果您是 Maven 新手，以下的 pom.xml 片段會精確顯示需要加入的內容。

Maven 設定

在您的 pom.xml 中加入以下設定，即可將 GroupDocs.Watermark 作為相依加入：

<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 版本下載 取得最新版本。

取得授權

  • 免費試用： 下載試用套件以體驗核心功能。
  • 臨時授權： 從 GroupDocs 入口網站取得限時金鑰，以延長測試時間。
  • 商業授權： 購買完整授權，以無限制的正式環境使用並獲得優先支援。

如何一步步在 Java 中添加圖片水印

Watermark 類別代表可進行水印操作的文件。ImageSearchOptions 用於設定搜尋圖片水印的條件。WatermarkSearchResult 保存搜尋結果中找到的所有水印集合。setImage() 方法可替換水印的圖片，而 document.save() 則將修改後的文件寫入磁碟。

載入目標文件、定位任何現有水印，並以新圖片取代——只需三個簡潔步驟。以下的直接說明先概述整體流程，再逐一說明每個細節。

使用 Watermark.load() 載入 PDF（或其他支援的檔案），設定 ImageSearchOptions 物件以根據提供的雜湊值搜尋匹配的水印，遍歷返回的集合，呼叫 setImage() 並傳入新的位元組陣列，最後以 save() 儲存修改後的文件。此模式適用於 PDF、Word、Excel、PowerPoint 以及圖片檔案，確保僅修改目標水印。

步驟 1：載入圖片檔案（Java）

要取代水印，首先需要將新圖片讀取為位元組陣列。以下程式碼會將磁碟上的任意圖片檔案讀入記憶體，之後即可傳入 watermark API 使用。

import com.groupdocs.watermark.Watermarker;

public class Main {
    public static void main(String[] args) {
        Watermarker watermarker = new Watermarker("YOUR_DOCUMENT_PATH.pdf");
        // Proceed to use GroupDocs.Watermark functionalities.
    }
}

說明： 這段程式碼使用 FileInputStream 並以 try‑with‑resources 包裝，確保串流會自動關閉。這可防止檔案句柄洩漏，對於批次處理大量文件時尤為重要。

步驟 2：在文件中搜尋水印

接著，設定搜尋條件讓引擎知道要定位哪些水印。您可以依圖片雜湊、尺寸或透明度匹配；以下範例採用雜湊方式以獲得高精度。

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

public class LoadImageData {
    private static final String IMAGE_PNG_PATH = "YOUR_DOCUMENT_DIRECTORY/image.png";

    public byte[] loadImageData() throws Exception {
        File imageFile = new File(IMAGE_PNG_PATH);
        byte[] imageData = new byte[(int) imageFile.length()];
        try (InputStream imageInputStream = new FileInputStream(imageFile)) {
            imageInputStream.read(imageData); // Read the file into the byte array.
        }
        return imageData;
    }
}

說明： Watermark.search() 會返回 WatermarkSearchResult 集合。透過提供帶有原始水印雜湊值的 ImageSearchOptions 物件，API 會過濾掉不相關的圖形，提供乾淨的匹配清單。

步驟 3：替換水印中的圖片

最後，遍歷找到的水印，將每個水印的圖片資料以步驟 1 中建立的位元組陣列取代。更新後，將文件儲存為新檔案以保留原始檔。

import com.groupdocs.watermark.Watermarker;
import com.groupdocs.watermark.search.ImageDctHashSearchCriteria;
import com.groupdocs.watermark.search.PossibleWatermarkCollection;

public class SearchForWatermarks {
    private static final String INPUT_PDF_PATH = "YOUR_DOCUMENT_DIRECTORY/document.pdf";

    public PossibleWatermarkCollection searchWatermarks() throws Exception {
        Watermarker watermarker = new Watermarker(INPUT_PDF_PATH);
        ImageDctHashSearchCriteria searchCriteria = new ImageDctHashSearchCriteria("YOUR_DOCUMENT_DIRECTORY/logo.bmp");
        
        return watermarker.search(searchCriteria);
    }
}

說明： 迴圈會對每個匹配呼叫 watermark.setImage(newImageBytes)，然後使用 document.save(outputPath) 保存變更。由於 API 直接在原文件上操作，無論替換多少水印，只需一次儲存即可。

常見問題與除錯

LoadOptions 允許您在開啟文件時指定參數，例如密碼或載入模式。LoadMode 列舉定義了檔案的載入方式，例如使用 STREAM 進行串流存取。

症狀可能原因解決方案
找不到任何水印搜尋雜湊不匹配（解析度或色深不同）從完全相同的來源檔案產生雜湊，或使用 ImageSearchOptions.setSimilarity(0.85) 允許模糊匹配。
大型 PDF 發生記憶體不足錯誤整個文件被載入記憶體使用 Watermark.load(inputPath, LoadOptions.create().setLoadMode(LoadMode.STREAM)) 以串流方式載入檔案。
儲存的文件損毀輸出串流未正確關閉確保對輸出串流使用 try‑with‑resources，或在儲存後呼叫 document.close()。
新水印位置偏移原始水印具有旋轉或縮放的中繼資料保留原始 Watermark.getTransform() 設定，並透過 watermark.setTransform(originalTransform) 套用到新圖片。

常見問答

Q: 我可以在受密碼保護的 PDF 上添加水印嗎？
A: 可以。使用 Watermark.load(path, new LoadOptions(password)) 載入文件，API 會為處理自動解密。

Q: GroupDocs.Watermark 支援 SVG 圖片嗎？
A: 函式庫可以先將 SVG 轉為 PNG 再嵌入，但目前不支援直接插入 SVG。

Q: 單次呼叫最多能處理多少頁？
A: 由於串流架構，API 可處理 500 頁以上 的文件而不需將整個檔案載入記憶體。

Q: 能否在同一文件中加入多個不同的水印？
A: 當然可以。為每張圖片建立獨立的 Watermark 物件，並對每個呼叫 document.add(watermark)。

Q: Java SDK 支援哪些平台？
A: 支援 Windows、Linux 與 macOS，且函式庫可在任何相容 JVM 的環境執行，包括 Docker 容器。

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

import com.groupdocs.watermark.Watermarker;
import com.groupdocs.watermark.search.PossibleWatermarkCollection;

public class ReplaceImageInWatermarks {
    private static final String OUTPUT_PDF_PATH = "YOUR_OUTPUT_DIRECTORY/modified_document.pdf";
    
    public void replaceImages(PossibleWatermarkCollection watermarks, byte[] newImageData) throws Exception {
        Watermarker watermarker = new Watermarker(INPUT_PDF_PATH);

        for (PossibleWatermark watermark : watermarks) {
            try {
                watermark.setImageData(newImageData);
            } catch (Exception e) {
                // Handle exceptions related to unsupported formats or entities.
            }
        }

        watermarker.save(OUTPUT_PDF_PATH);
        watermarker.close();
    }
}

相關教學