在 Java 中為 PDF 文件添加圖像水印

Fri, 28 Aug 2026 19:41:04 +0000

在 PDF 文件中添加視覺識別標誌對於保護知識產權和為文件建立品牌形象至關重要。 GroupDocs.Watermark Cloud SDK for Java 提供簡單的 API，允許直接從 Java 應用程式將圖像水印嵌入 PDF。在本教程中，您將學習如何在 Java 中向 PDF 文檔添加圖像水印，查看完整的工作範例，並探索用於雲端整合的等效 cURL REST 調用。

在 Java 中的 PDF 文件添加圖像水印（5 步）

初始化 API 客戶端：使用您的客戶端 ID 和密鑰建立 ApiClient 實例。

ApiClient apiClient = new ApiClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
WatermarkApi watermarkApi = new WatermarkApi(apiClient);

此步驟將您的 Java 程式碼連接到 GroupDocs.Watermark Cloud 服務。詳情請參閱 API 參考。

指定來源 PDF 檔案：建立指向您想要加上浮水印的 PDF 的 FileInfo 物件。

FileInfo fileInfo = new FileInfo();
fileInfo.setFilePath("input.pdf");

檔案必須在請求之前上傳至您的 GroupDocs 儲存空間。

配置圖像水印：定義圖像路徑、不透明度、縮放因子、旋轉和對齊方式。

ImageWatermark imageWatermark = new ImageWatermark();
imageWatermark.setImagePath("watermark.png");
imageWatermark.setOpacity(0.5);
imageWatermark.setScaleFactor(0.3);
imageWatermark.setHorizontalAlignment(HorizontalAlignment.CENTER);
imageWatermark.setVerticalAlignment(VerticalAlignment.CENTER);
imageWatermark.setMargin(new Margin(10, 10, 10, 10));

調整這些值以實現所需的外觀，不透明度控制透明度，而縮放因子決定相對於頁面的大小。

設定浮水印選項與輸出路徑：將檔案資訊和浮水印結合成 WatermarkOptions 物件。

WatermarkOptions options = new WatermarkOptions();
options.setFileInfo(fileInfo);
options.setImageWatermark(imageWatermark);
options.setOutputPath("output.pdf");

outputPath 告訴服務將產生的 PDF 存放在哪裡。

執行請求：建立 AddWatermarkRequest 並呼叫 API。處理成功或錯誤回應。

AddWatermarkRequest request = new AddWatermarkRequest(options);
try {
    AddWatermarkResponse response = watermarkApi.addWatermark(request);
    System.out.println("Watermark added successfully. Output file: " + response.getPath());
} catch (Exception e) {
    System.err.println("Error adding watermark: " + e.getMessage());
}

執行後，已加水印的 PDF 會位於您指定的位置。

完整程式碼範例：在 Java 中為 PDF 文件添加圖像水印

以下示例展示了從客戶端初始化到保存加水印 PDF 的完整實作。

import com.groupdocs.cloud.watermark.api.WatermarkApi;
import com.groupdocs.cloud.watermark.client.ApiClient;
import com.groupdocs.cloud.watermark.model.AddWatermarkRequest;
import com.groupdocs.cloud.watermark.model.AddWatermarkResponse;
import com.groupdocs.cloud.watermark.model.FileInfo;
import com.groupdocs.cloud.watermark.model.ImageWatermark;
import com.groupdocs.cloud.watermark.model.Margin;
import com.groupdocs.cloud.watermark.model.WatermarkOptions;
import com.groupdocs.cloud.watermark.model.enums.HorizontalAlignment;
import com.groupdocs.cloud.watermark.model.enums.VerticalAlignment;

public class AddImageWatermarkExample {
    public static void main(String[] args) {
        // Initialize API client (replace with your actual credentials)
        ApiClient apiClient = new ApiClient("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
        WatermarkApi watermarkApi = new WatermarkApi(apiClient);

// Input PDF file information
        FileInfo fileInfo = new FileInfo();
        fileInfo.setFilePath("input.pdf");

// Image watermark configuration
        ImageWatermark imageWatermark = new ImageWatermark();
        imageWatermark.setImagePath("watermark.png");          // Path to watermark image
        imageWatermark.setOpacity(0.5);                        // 50% opacity
        imageWatermark.setScaleFactor(0.3);                    // 30% of page size
        imageWatermark.setRotationAngle(0);                    // No rotation
        imageWatermark.setHorizontalAlignment(HorizontalAlignment.CENTER);
        imageWatermark.setVerticalAlignment(VerticalAlignment.CENTER);
        imageWatermark.setMargin(new Margin(10, 10, 10, 10));  // 10 points margin on all sides

// Watermark options
        WatermarkOptions options = new WatermarkOptions();
        options.setFileInfo(fileInfo);
        options.setImageWatermark(imageWatermark);
        options.setOutputPath("output.pdf"); // Resulting PDF with watermark

// Create request and call API
        AddWatermarkRequest request = new AddWatermarkRequest(options);
        try {
            AddWatermarkResponse response = watermarkApi.addWatermark(request);
            System.out.println("Watermark added successfully. Output file: " + response.getPath());
        } catch (Exception e) {
            System.err.println("Error adding watermark: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

注意： 此代碼示例演示了核心功能。在將其用於您的項目之前，請確保更新文件路徑（input.pdf、watermark.png、output.pdf）以匹配實際文件位置，驗證所有必需的依賴項已正確安裝，並在開發環境中徹底測試。如遇到任何問題，請參閱官方文檔或聯繫支持團隊尋求幫助。

使用 cURL 和 REST API 為 PDF 文檔添加圖像水印

以下是您可以使用 cURL 的 REST 呼叫，以在不編寫 Java 程式碼的情況下達成相同的結果。

取得存取權杖

curl -X POST "https://api.groupdocs.cloud/v2.0/auth/token" \
     -H "Content-Type: application/json" \
     -d '{"client_id":"YOUR_CLIENT_ID","client_secret":"YOUR_CLIENT_SECRET"}'

回應中包含用於後續呼叫的 access_token。

上傳來源 PDF

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/upload?path=input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@/path/to/input.pdf"

上傳水印圖像

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/upload?path=watermark.png" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@/path/to/watermark.png"

新增圖片浮水印

curl -X POST "https://api.groupdocs.cloud/v2.0/watermark/add" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "fileInfo": { "filePath": "input.pdf" },
           "imageWatermark": {
               "imagePath": "watermark.png",
               "opacity": 0.5,
               "scaleFactor": 0.3,
               "horizontalAlignment": "Center",
               "verticalAlignment": "Center",
               "margin": { "top": 10, "right": 10, "bottom": 10, "left": 10 }
           },
           "outputPath": "output.pdf"
         }'

此請求鏡像了 Java 程式碼的邏輯，套用相同的透明度、縮放比例和對齊設定。

下載帶有水印的 PDF

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/download?path=output.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.pdf

如需了解請求正文和支援的參數的更多詳細資訊，請參閱官方 API 文件。

安裝與設定 GroupDocs.Watermark Cloud SDK for Java

將 Maven 依賴項添加到您的 pom.xml（或等效的 Gradle 片段）。該庫託管於 Maven Central。


    com.groupdocs
    groupdocs-watermark-cloud
    23.8

您還需要一個有效的 GroupDocs Cloud 帳戶。從 GroupDocs portal 取得您的 Client ID 和 Client Secret。不需要額外的執行時安裝，因為 SDK 直接與雲端服務通信。

微調 PDF 文檔的圖像水印選項

SDK 提供了多個屬性，讓您可以控制浮水印的視覺外觀。

調整不透明度

imageWatermark.setOpacity(0.75); // 75% opacity for a more visible watermark

不透明度值範圍從 0.0（完全透明）到 1.0（完全不透明）。

更改比例因子

imageWatermark.setScaleFactor(0.5); // Watermark occupies 50% of the page width

比例因子決定浮水印相對於頁面尺寸的大小。

設定對齊與邊距

imageWatermark.setHorizontalAlignment(HorizontalAlignment.RIGHT);
imageWatermark.setVerticalAlignment(VerticalAlignment.BOTTOM);
imageWatermark.setMargin(new Margin(20, 20, 20, 20));

這些設定會將浮水印放置在右下角，邊距為 20 點。

欲取得可配置屬性的完整清單，請參閱 API 參考。

結論

在 Java 中為 PDF 文檔添加圖像水印是一項直接的任務，只要使用 GroupDocs.Watermark Cloud SDK for Java。SDK 處理所有低層次的 PDF 操作，讓您專注於不透明度、縮放和定位等視覺方面。無論您偏好本機 Java 實現還是基於雲的 cURL 工作流程，都能在不犧牲性能的情況下實現相同的高品質結果。請記得為生產環境獲取適當的許可證；產品頁面上提供了價格細節，亦可使用臨時許可證頁面進行評估。

常見問題

如何在 Java 中向 PDF 添加圖像水印而不失去品質？
使用 scaleFactor 屬性根據頁面大小調整水印，並保持來源 PDF 的原始 DPI。SDK 會保留 PDF 的解析度，因此水印在任何縮放級別下都保持清晰。
我可以在同一個 PDF 中添加多個水印嗎？
是的。建立具有不同配置的獨立 ImageWatermark 物件，然後透過多次呼叫 addWatermark 依序加入，或將它們加入請求中的清單。
支援的浮水印圖像格式有哪些？
API 接受常見的圖像類型，例如 PNG、JPG、BMP、GIF 和 TIFF。建議使用 PNG 以獲得無損品質和透明度支援。
是否有方法在應用水印之前預覽它？
您可以使用 GroupDocs.Watermark Cloud SDK for Java 生成帶有水印的臨時 PDF，並下載以供審核。這使用相同的 addWatermark 調用，將輸出路徑指向臨時位置。

java pdf watermark on Document Processing REST APIs | GroupDocs Cloud