إضافة علامة مائية صورة إلى مستندات PDF في Java

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

إضافة معرف بصري إلى ملفات PDF أمر ضروري لحماية الملكية الفكرية وتوثيق العلامة التجارية للوثائق. يقدم GroupDocs.Watermark Cloud SDK for Java واجهة برمجة تطبيقات بسيطة لدمج علامات مائية صورة مباشرةً في ملفات PDF من تطبيق Java الخاص بك. في هذا البرنامج التعليمي ستتعلم كيفية إضافة علامة مائية صورة إلى مستندات PDF باستخدام Java، وستشاهد مثالًا عمليًا كاملاً، وتستكشف مكالمات cURL REST المكافئة للتكامل السحابي.

إضافة علامة مائية صورة إلى مستندات PDF في Java في 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 في Java

يوضح المثال التالي التنفيذ الكامل من تهيئة العميل إلى حفظ ملف 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

لمزيد من التفاصيل حول أجسام الطلب والمعلمات المدعومة، راجع الوثائق الرسمية لواجهة برمجة التطبيقات.

تثبيت وتكوين GroupDocs.Watermark Cloud SDK for Java

أضف اعتماد Maven إلى ملف pom.xml الخاص بك (أو المقتطف المكافئ لـ Gradle). المكتبة مستضافة على Maven Central.


    com.groupdocs
    groupdocs-watermark-cloud
    23.8

ستحتاج أيضًا إلى حساب GroupDocs Cloud صالح. استرجع معرف العميل و سر العميل من GroupDocs portal. لا يلزم أي تثبيت إضافي في وقت التشغيل لأن 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 في Java هي مهمة بسيطة عندما تستخدم GroupDocs.Watermark Cloud SDK for Java. يتعامل SDK مع جميع عمليات تعديل PDF منخفضة المستوى، مما يتيح لك التركيز على الجوانب البصرية مثل الشفافية، والتحجيم، والتموضع. سواء كنت تفضل تنفيذًا أصليًا بلغة Java أو سير عمل سحابي يعتمد على cURL، يمكن تحقيق نفس النتائج عالية الجودة دون التضحية بالأداء. تذكر الحصول على ترخيص مناسب للاستخدام في الإنتاج؛ تفاصيل التسعير متوفرة على صفحة المنتج ويمكن استخدام temporary license page للتقييم.

الأسئلة المتكررة

كيف يمكنني إضافة علامة مائية صورة إلى PDF في Java دون فقدان الجودة؟
استخدم الخاصية scaleFactor لتحديد حجم العلامة المائية نسبة إلى الصفحة والحفاظ على DPI الأصلي لملف PDF المصدر. يحافظ 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

إضافة علامة مائية صورة إلى مستندات PDF في Java