افزودن واترمارک تصویر به اسناد PDF در جاوا

اضافه کردن یک شناسه بصری به فایل‌های PDF برای حفاظت از مالکیت فکری و برندینگ اسناد ضروری است. GroupDocs.Watermark Cloud SDK for Java یک API ساده برای جاسازی واترمارک‌های تصویری به طور مستقیم در PDFها از برنامه Java شما ارائه می‌دهد. در این آموزش، خواهید آموخت که چگونه واترمارک تصویری را به اسناد PDF در Java اضافه کنید، یک مثال کامل و عملی را ببینید و تماس‌های معادل cURL REST برای ادغام ابری را بررسی کنید.

افزودن واترمارک تصویر به اسناد PDF در جاوا در 5 گام

راه‌اندازی کلاینت API: یک نمونه ApiClient با شناسه کلاینت و رمز عبور خود ایجاد کنید.

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

این مرحله کد Java شما را به سرویس GroupDocs.Watermark Cloud متصل می‌کند. برای جزئیات بیشتر به مستندات API مراجعه کنید.

مشخص کردن فایل PDF منبع: یک شیء FileInfo بسازید که به PDF مورد نظر برای افزودن واترمارک اشاره دارد.

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 با واترمارک در مکانی که مشخص کرده‌اید در دسترس است.

مثال کامل کد: افزودن واترمارک تصویر به اسناد 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) با مکان‌های واقعی فایل‌های شما مطابقت دارد، اطمینان حاصل کنید تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه کنید.

اعمال واترمارک تصویر به اسناد PDF با استفاده از cURL و REST API

در زیر تماس‌های REST که می‌توانید با cURL استفاده کنید تا همان نتیجه را بدون نوشتن کد 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 میزبانی می‌شود.

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-watermark-cloud</artifactId>
    <version>23.8</version>
</dependency>

شما همچنین به یک حساب معتبر GroupDocs Cloud نیاز دارید. Client ID و Client Secret خود را از پرتال GroupDocs دریافت کنید. نصب زمان اجرا اضافی لازم نیست زیرا 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 مراجعه کنید.

نتیجه‌گیری

افزودن واترمارک تصویر به اسناد PDF در جاوا کاری ساده است هنگامی که از GroupDocs.Watermark Cloud SDK for Java استفاده می‌کنید. SDK تمام عملیات‌های سطح پایین PDF را مدیریت می‌کند و به شما امکان می‌دهد بر جنبه‌های بصری مانند شفافیت، مقیاس‌بندی و موقعیت‌یابی تمرکز کنید. چه پیاده‌سازی بومی جاوا را ترجیح دهید و چه گردش کار مبتنی بر cURL در ابر، می‌توانید نتایج با کیفیت بالا را بدون کاهش عملکرد به دست آورید. به‌خاطر داشته باشید که برای استفاده در محیط تولید یک لایسنس مناسب دریافت کنید؛ جزئیات قیمت‌گذاری در صفحه محصول موجود است و می‌توانید برای ارزیابی از صفحه لایسنس موقت استفاده کنید.

سوالات متداول

چگونه می‌توانم واترمارک تصویر را به PDF در جاوا اضافه کنم بدون از دست دادن کیفیت؟
از ویژگی scaleFactor برای اندازه‌گیری واترمارک نسبت به صفحه استفاده کنید و DPI اصلی PDF منبع را حفظ کنید. SDK وضوح PDF را حفظ می‌کند، بنابراین واترمارک در هر سطح زوم واضح باقی می‌ماند.
آیا می‌توانم چندین واترمارک به یک PDF اضافه کنم؟
بله. اشیاء ImageWatermark جداگانه‌ای با پیکربندی‌های مختلف ایجاد کنید و آنها را به‌صورت متوالی با فراخوانی addWatermark چندین بار یا با افزودن آنها به یک لیست در درخواست اضافه کنید.
فرمت‌های تصویر پشتیبانی‌شده برای واترمارک چیست؟
API انواع تصویر رایج مانند PNG، JPG، BMP، GIF و TIFF را می‌پذیرد. PNG برای کیفیت بدون افت و پشتیبانی از شفافیت توصیه می‌شود.
آیا راهی برای پیش‌نمایش واترمارک قبل از اعمال آن وجود دارد؟
شما می‌توانید از GroupDocs.Watermark Cloud SDK for Java برای تولید یک PDF موقت با واترمارک استفاده کنید و آن را برای بررسی دانلود کنید. این کار از همان فراخوانی addWatermark با مسیر خروجی که به یک مکان موقت اشاره دارد، استفاده می‌کند.

افزودن واترمارک تصویر به اسناد PDF در جاوا در 5 گام#

مثال کامل کد: افزودن واترمارک تصویر به اسناد PDF در جاوا#

اعمال واترمارک تصویر به اسناد PDF با استفاده از cURL و REST API#

نصب و پیکربندی GroupDocs.Watermark Cloud SDK for Java#

تنظیم دقیق گزینه‌های واترمارک تصویر برای اسناد PDF#

تنظیم شفافیت#

تغییر ضریب مقیاس#

تنظیم تراز و حاشیه‌ها#

نتیجه‌گیری#

سوالات متداول#

Read More#