在 Java 中向 PDF 文档添加图像水印

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

向 PDF 文件添加可视标识对于保护知识产权和为文档进行品牌化至关重要。 GroupDocs.Watermark Cloud SDK for Java 提供了一个直接在 Java 应用程序中将图像水印嵌入 PDF 的简便 API。在本教程中，您将学习如何在 Java 中向 PDF 文档添加图像水印，查看完整的工作示例，并探索用于云集成的等效 cURL REST 调用。

在 Java 中的 5 步为 PDF 文档添加图像水印

初始化 API 客户端: 使用您的 client ID 和 secret 创建 ApiClient 实例。

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

此步骤将您的 Java 代码连接到 GroupDocs.Watermark Cloud 服务。请参阅 API reference 获取更多详情。

指定源 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 门户获取您的 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 工作流，都可以在不牺牲性能的前提下实现同样高质量的结果。请记得为生产使用获取合适的许可证；产品页面上提供了定价详情，您也可以使用临时许可证页面进行评估。

FAQs

如何在 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