اضافه کردن عنوانهای پویا، زیرنویسها یا پیامهای تبلیغاتی به GIFهای انیمیشنی یک نیاز رایج برای برنامههای وب و موبایل مدرن است. GroupDocs.Watermark Cloud SDK for Java کتابخانه قدرتمند مبتنی بر REST را فراهم میکند که این کار را ساده میسازد. در این راهنما یاد خواهید گرفت چگونه متن Overlay را به GIF با استفاده از REST در Java اضافه کنید، یک پیادهسازی کامل Java را ببینید، دستورات معادل cURL را بررسی کنید و مراحل تنظیم مورد نیاز را درک کنید.
افزودن متن روی GIF با استفاده از REST در Java - کد نمونه
این مثال نشان میدهد که چگونه یک واترمارک متنی را پیکربندی کرده و آن را بر روی هر فریم یک فایل GIF اعمال کنید.
import com.groupdocs.watermark.cloud.api.WatermarkApi;
import com.groupdocs.watermark.cloud.client.ApiException;
import com.groupdocs.watermark.cloud.client.Configuration;
import com.groupdocs.watermark.cloud.model.AddWatermarkRequest;
import com.groupdocs.watermark.cloud.model.AddWatermarkResponse;
import com.groupdocs.watermark.cloud.model.FileInfo;
import com.groupdocs.watermark.cloud.model.OutputFileInfo;
import com.groupdocs.watermark.cloud.model.TextWatermarkOptions;
import com.groupdocs.watermark.cloud.model.HorizontalAlignment;
import com.groupdocs.watermark.cloud.model.VerticalAlignment;
public class AddTextOverlayToGif {
public static void main(String[] args) {
// Initialize API configuration (replace with your actual clientId and clientSecret)
Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
WatermarkApi watermarkApi = new WatermarkApi(config);
// Prepare input file information
FileInfo inputFile = new FileInfo();
inputFile.setFilePath("input.gif"); // Path to the source GIF in the storage
inputFile.setStorageName("MyStorage"); // Optional: name of the storage
// Prepare output file information
OutputFileInfo outputFile = new OutputFileInfo();
outputFile.setFilePath("output.gif"); // Desired path for the watermarked GIF
outputFile.setStorageName("MyStorage"); // Optional: name of the storage
// Configure text watermark options
TextWatermarkOptions textOptions = new TextWatermarkOptions();
textOptions.setText("Sample Watermark");
textOptions.setFontFamily("Arial");
textOptions.setFontSize(24.0);
textOptions.setColor("#FF0000"); // Red color in HEX
textOptions.setOpacity(0.5); // 50% opacity
textOptions.setRotationAngle(0.0);
textOptions.setHorizontalAlignment(HorizontalAlignment.CENTER);
textOptions.setVerticalAlignment(VerticalAlignment.MIDDLE);
textOptions.setPageRange("1-"); // Apply to all frames/pages
// Build the request
AddWatermarkRequest request = new AddWatermarkRequest();
request.setFileInfo(inputFile);
request.setOutputFileInfo(outputFile);
request.setOptions(textOptions);
try {
// Execute the request
AddWatermarkResponse response = watermarkApi.addWatermark(request);
System.out.println("Watermark added successfully. Output file: " + response.getPath());
} catch (ApiException e) {
System.err.println("Error while adding watermark: " + e.getMessage());
e.printStackTrace();
}
}
}
توجه: این مثال کد عملکرد اصلی را نشان میدهد. قبل از استفاده از آن در پروژهتان، مطمئن شوید که مسیرهای فایل و مقادیر پیکربندی را بهگونهای بهروزرسانی کنید که با محیط واقعی شما مطابقت داشته باشد، اطمینان حاصل کنید که تمام وابستگیهای مورد نیاز بهدرستی نصب شدهاند و بهطور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه کنید.
افزودن متن بر روی GIF با استفاده از REST API و cURL
در زیر دستورات cURL که همان عملیات را از طریق ترمینال انجام میدهند، آمدهاند. این دستورات جریان کامل REST شامل احراز هویت، بارگذاری، افزودن واترمارک و دانلود را نشان میدهند.
# 1. Obtain an access token
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"}'
در فراخوانیهای زیر، YOUR_ACCESS_TOKEN را با توکنی که در بالا برگردانده شد جایگزین کنید.
# 2. Upload the source GIF to storage
curl -X PUT "https://api.groupdocs.cloud/v2.0/storage/file/input.gif" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/octet-stream" \
--data-binary @path/to/local/input.gif
# 3. Add text overlay to the GIF
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.gif", "storageName": "MyStorage" },
"outputFileInfo": { "filePath": "output.gif", "storageName": "MyStorage" },
"options": {
"text": "Sample Watermark",
"fontFamily": "Arial",
"fontSize": 24,
"color": "#FF0000",
"opacity": 0.5,
"horizontalAlignment": "Center",
"verticalAlignment": "Middle",
"pageRange": "1-"
}
}'
# 4. Download the watermarked GIF
curl -X GET "https://api.groupdocs.cloud/v2.0/storage/file/output.gif" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-o path/to/local/output.gif
برای جزئیات بیشتر درباره بدنههای درخواست و قالبهای پاسخ، مستندات رسمی API را ببینید.
تجزیه و تحلیل افزودن متن پوشش به GIF با استفاده از REST در جاوا - نحوه کار
- مقداردهی اولیه کلاینت API -
new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET")یک شیء پیکربندی ایجاد میکند که اعتبارنامههای شما را نگه میدارد. نمونهWatermarkApiاز این پیکربندی برای امضای هر درخواست استفاده میکند.
Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
WatermarkApi watermarkApi = new WatermarkApi(config);
مشخص کردن فایلهای منبع و مقصد -
FileInfoوOutputFileInfoبه سرویس میگویند که کجا GIF اصلی را بخوانند و کجا نتیجه را بنویسند. هر دو میتوانند به نام ذخیرهسازی سفارشی ارجاع دهند.FileInfo inputFile = new FileInfo(); inputFile.setFilePath("input.gif"); inputFile.setStorageName("MyStorage");پیکربندی واترمارک متنی -
TextWatermarkOptionsتمام ویژگیهای بصری را شامل میشود: متن، فونت، اندازه، رنگ، شفافیت، چرخش و تراز. تنظیمpageRangeبه"1-"اطمینان میدهد که هر فریم از GIF انیمیشنی پوشش را دریافت میکند.TextWatermarkOptions textOptions = new TextWatermarkOptions(); textOptions.setText("Sample Watermark"); textOptions.setFontFamily("Arial"); textOptions.setFontSize(24.0); textOptions.setColor("#FF0000"); textOptions.setOpacity(0.5); textOptions.setHorizontalAlignment(HorizontalAlignment.CENTER); textOptions.setVerticalAlignment(VerticalAlignment.MIDDLE); textOptions.setPageRange("1-");ساخت و ارسال درخواست -
AddWatermarkRequestبستهبندی اطلاعات فایل و گزینهها را انجام میدهد. فراخوانیwatermarkApi.addWatermark(request)عملیات را بر روی سرور انجام میدهد و مسیر فایل پردازششده را برمیگرداند.
AddWatermarkRequest request = new AddWatermarkRequest();
request.setFileInfo(inputFile);
request.setOutputFileInfo(outputFile);
request.setOptions(textOptions);
AddWatermarkResponse response = watermarkApi.addWatermark(request);
- پردازش پاسخ - پاسخ شامل مسیر فایل خروجی است. در یک برنامه واقعی معمولاً فایل را دانلود میکنید یا مسیر را به سرویس دیگری میسپارید.
برای دریافت فهرست کامل کلاسها و ویژگیها، به مرجع API مراجعه کنید.
نصب و پیکربندی GroupDocs.Watermark Cloud SDK for Java
وابستگی Maven را به pom.xml خود اضافه کنید (یا ورودی معادل Gradle). این نسخه 23.8 SDK را بارگیری میکند.
<dependency>
<groupId>com.groupdocs</groupId>
<artifactId>groupdocs-watermark-cloud</artifactId>
<version>23.8</version>
</dependency>
پیشنیازها
- Java 8 یا بالاتر
- یک حساب فعال GroupDocs Cloud
- Client ID و Client Secret (در داشبورد GroupDocs Cloud در دسترس است)
مثال پیکربندی
Configuration config = new Configuration("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
جدیدترین JARها را از صفحه دانلود دریافت کنید. برای استفاده در محیط تولید، یک لایسنس معتبر که از صفحه لایسنس موقت دریافت شده است را اعمال کنید.
نتیجهگیری
متن پوششی را به GIF با استفاده از REST در جاوا اضافه کنید و این کار تبدیل به یک عملیات قابل تکرار و سمت‑سرور میشود با کمک GroupDocs.Watermark Cloud SDK for Java. این SDK پیچیدگیهای پردازش فریمهای انیمیشنی را انتزاع میکند و به شما امکان میدهد بر محتوای زیرنویسها یا پیامهای تبلیغاتی خود تمرکز کنید. پس از ادغام کد نمونه یا جریان کاری cURL، میتوانید سبکهای قلم، رنگها و شفافیت را برای مطابقت با برند خود بهدقت تنظیم کنید. بهخاطر داشته باشید برای دریافت مجوز تولید، جزئیات قیمتگذاری در صفحه محصول موجود است و میتوانید برای تست یک مجوز موقت را از طریق صفحه مجوز موقت دریافت کنید. برنامهنویسی خوش!
سؤالات متداول
چگونه میتوانم پوشش متن را به GIF با استفاده از REST در Java اضافه کنم وقتی متن برای هر کاربر تغییر میکند؟
شیءTextWatermarkOptionsرا در زمان اجرا با رشته مخصوص به کاربر بسازید، سپس همان فراخوانیaddWatermarkرا اجرا کنید. API هر درخواست را به طور مستقل پردازش میکند، بنابراین محتوای پویا بهطور کامل پشتیبانی میشود.آیا میتوانم زیرنویسها را به یک GIF متحرک اضافه کنم بدون اینکه سرعت انیمیشن آن تحت تأثیر قرار گیرد؟
بله. واترمارک بر روی هر فریم اعمال میشود در حالی که تأخیر اصلی فریم حفظ میشود. کافی استpageRangeرا روی"1-"تنظیم کنید تا هر فریم همان پوشش را دریافت کند.چه قالبهایی برای رنگ متن پوشش پشتیبانی میشوند؟
SDK کدهای رنگ HEX (مثلاً#FF0000) و نامهای رنگ استاندارد HTML را میپذیرد. برای لیست کامل به مرجع API مراجعه کنید.آیا برای توسعه و تست به لایسنس نیاز دارم؟
یک لایسنس موقت برای ارزیابی و تست کافی است. برای استقرارهای تولیدی، یک لایسنس کامل از صفحه محصول خریداری کنید و آن را با استفاده از API لایسنسینگ SDK اعمال کنید.