آموزش گام به گام - تبدیل DOCX به PDF در جاوا

تبدیل فایل‌های DOCX به PDF یک نیاز مکرر هنگام ساخت جریان‌های کاری سند است که به فرمت جهانی و آماده چاپ نیاز دارند. GroupDocs.Conversion Cloud SDK for Java یک API قدرتمند ارائه می‌دهد که این کار را بدون وابستگی به Microsoft Office انجام می‌دهد. در این آموزش خواهید دید که چگونه کتابخانه را تنظیم کنید، تبدیل چندنخی را اجرا کنید، به‌صورت کارآمد با جریان‌ها کار کنید و بهترین روش‌های عملکردی را اعمال کنید. در پایان یک نمونه کد آماده‑به‑استفاده خواهید داشت که می‌توانید آن را در هر بک‌اند Java یکپارچه کنید.

مراحل انجام تبدیل DOCX به PDF در Java

مقداردهی اولیه کلاینت Conversion API – یک نمونه از ConversionApi را با استفاده از شناسه کلاینت و راز خود ایجاد کنید. این شیء برای تمام فراخوانی‌های بعدی استفاده خواهد شد.
```
ConversionApi api = new ConversionApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
```
بارگذاری فایل DOCX منبع – از UploadApi برای ارسال فایل DOCX به ذخیره‌سازی GroupDocs استفاده کنید. API یک شناسه فایل برمی‌گرداند که بعداً به آن ارجاع خواهید داد.
```
UploadApi upload = new UploadApi(api);
String fileId = upload.uploadFile("sample.docx");
```
پیکربندی گزینه‌های تبدیل – چندنخی را با تنظیم parallelism فعال کنید و خروجی مبتنی بر جریان را برای جلوگیری از فایل‌های موقت انتخاب کنید.
```
ConvertOptions options = new ConvertOptions();
options.setParallelism(4);               // Use 4 threads
options.setOutputFormat("pdf");
options.setUseStream(true);
```
اجرای تبدیل – متد convert را با شناسه فایل و گزینه‌ها فراخوانی کنید. نتیجه به صورت InputStream برگردانده می‌شود.
```
InputStream pdfStream = api.convert(fileId, options);
```
ذخیره PDF – InputStream را در مکان مورد نظر خود بنویسید و منابع را ببندید.
```
Files.copy(pdfStream, Paths.get("output.pdf"), StandardCopyOption.REPLACE_EXISTING);
pdfStream.close();
```

تبدیل DOCX به PDF در Java - مثال کامل کد

مثال زیر تمام مراحل را در یک برنامهٔ آماده برای کامپایل ترکیب می‌کند. این مثال تبدیل چندنخی، مدیریت جریان و پاک‌سازی صحیح منابع را نشان می‌دهد.

import com.groupdocs.conversion.cloud.api.ConversionApi;
import com.groupdocs.conversion.cloud.api.UploadApi;
import com.groupdocs.conversion.cloud.model.ConvertOptions;
import java.io.InputStream;
import java.nio.file.Files;
import java.nio.file.Paths;
import java.nio.file.StandardCopyOption;

public class DocxToPdfDemo {
    public static void main(String[] args) {
        // Initialize the API client
        ConversionApi conversionApi = new ConversionApi("YOUR_CLIENT_ID", "YOUR_CLIENT_SECRET");
        UploadApi uploadApi = new UploadApi(conversionApi);

try {
            // 1. Upload DOCX file
            String fileId = uploadApi.uploadFile("sample.docx");

// 2. Set conversion options (multithreading + stream output)
            ConvertOptions options = new ConvertOptions();
            options.setParallelism(4);          // Number of threads
            options.setOutputFormat("pdf");
            options.setUseStream(true);

// 3. Perform conversion
            InputStream pdfStream = conversionApi.convert(fileId, options);

// 4. Save the resulting PDF
            Files.copy(pdfStream, Paths.get("sample_converted.pdf"), StandardCopyOption.REPLACE_EXISTING);
            pdfStream.close();

System.out.println("Conversion completed successfully.");
        } catch (Exception e) {
            System.err.println("Error during conversion: " + e.getMessage());
            e.printStackTrace();
        }
    }
}

توجه: این مثال کد عملکرد اصلی را نشان می‌دهد. قبل از استفاده از آن در پروژه خود، مطمئن شوید مسیرهای فایل (sample.docx, sample_converted.pdf) به‌روز شده‌اند، تأیید کنید که تمام وابستگی‌های مورد نیاز به‌درستی نصب شده‌اند و به‌طور کامل در محیط توسعه خود تست کنید. اگر با مشکلی مواجه شدید، لطفاً به مستندات رسمی مراجعه کنید یا برای دریافت کمک به تیم پشتیبانی مراجعه نمایید.

تبدیل سند DOCX به PDF از طریق REST API با استفاده از cURL

می‌توانید همان تبدیل را با استفاده از نقاط انتهایی REST که توسط سرویس ابری ارائه شده‌اند، انجام دهید. در زیر دستورات cURL مورد نیاز آورده شده است.

دریافت توکن دسترسی - احراز هویت با اعتبارهای کلاینت خود.

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

بارگذاری فایل DOCX - از توکن مرحلهٔ قبلی استفاده کنید.

curl -X POST "https://api.groupdocs.cloud/v2.0/storage/upload" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -F "file=@sample.docx"

شروع تبدیل - درخواست خروجی PDF با فعال‌سازی چندنخی.

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "inputFilePath":"sample.docx",
           "outputFormat":"pdf",
           "options":{"parallelism":4}
         }'

دانلود PDF تبدیل‌شده - output_file_id را با شناسه‌ای که در پاسخ قبلی برگردانده شد جایگزین کنید.

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/download/output_file_id.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o converted.pdf

برای دریافت فهرست کامل نقاط انتهایی و پارامترها، به مستندات رسمی API مراجعه کنید.

نصب و راه‌اندازی در جاوا

Add the Maven dependency - Include the SDK in your pom.xml.

<dependency>
    <groupId>com.groupdocs</groupId>
    <artifactId>groupdocs-conversion-cloud</artifactId>
    <version>2.0.0</version>
</dependency>

Install the library - Run the Maven command to fetch the package.
```
mvn install com.groupdocs:groupdocs-conversion-cloud
```
Download the latest release - You can also obtain the JAR directly from the download page.
Apply a temporary license for testing - Register at the temporary license page and set the license file in your code if needed.
Configure your credentials - Store client_id and client_secret securely, for example in environment variables.

آموزش تبدیل DOCX به PDF در Java با GroupDocs.Conversion

GroupDocs.Conversion Cloud SDK پیچیدگی‌های تبدیل فرمت را انتزاع می‌کند و به شما امکان می‌دهد بر منطق کسب‌وکار تمرکز کنید. API از طیف گسترده‌ای از فرمت‌های منبع و هدف، مدیریت خودکار فونت‌ها و رندرینگ با دقت بالا پشتیبانی می‌کند. چون این سرویس در ابر اجرا می‌شود، از هزینه نصب اجزای Office روی سرورهای خود جلوگیری می‌کنید.

GroupDocs.Conversion ویژگی‌هایی که برای این کار مهم هستند

پردازش مبتنی بر جریان - با InputStream/OutputStream کار می‌کند تا I/O دیسک را به حداقل برساند.
تبدیل چندنخی - تنظیم parallelism رندر صفحات را بین هسته‌های CPU توزیع می‌کند و زمان تبدیل فایل‌های بزرگ DOCX را به طور چشمگیری کاهش می‌دهد.
حفظ چیدمان و تصاویر - تمام تصاویر، جداول و سبک‌های جاسازی‌شده در PDF نهایی حفظ می‌شوند.
زیرساخت ابری مقیاس‌پذیر - بدون نیاز به سخت‌افزار اضافی، بارهای کاری با حجم بالا را مدیریت می‌کند.

کار با جریان‌ها و گزینه‌های خروجی

هنگام کار با اسناد بزرگ، برای حفظ مصرف کم حافظه از جریان‌ها استفاده کنید:

InputStream input = new FileInputStream("large.docx");
ConvertOptions opts = new ConvertOptions();
opts.setUseStream(true);          // Enable streaming
opts.setParallelism(8);           // Increase thread count for big files
InputStream pdf = conversionApi.convert(input, opts);

SDK به‌صورت خودکار داده‌ها را بافر می‌کند، اما اگر به کنترل دقیق‌تری نیاز دارید می‌توانید اندازه بافرها را از طریق گزینه bufferSize تنظیم دقیق کنید.

بهینه‌سازی عملکرد تبدیل DOCX به PDF

تنظیم parallelism بر اساس تعداد هسته‌های CPU موجود؛ مقدار ۴‑۸ در اکثر سرورها به خوبی کار می‌کند.
استفاده مجدد از نمونه ConversionApi در چندین تبدیل برای جلوگیری از هزینه‌های مکرر احراز هویت.
ترجیح خروجی به‌صورت جریان به جای فایل‌های موقت برای کاهش تاخیر دیسک.
نظارت بر سهمیه‌های API - سرویس ابری محدودیت‌های درخواست را اعمال می‌کند؛ در صورت امکان چندین فایل را به‌صورت دسته‌ای پردازش کنید.

بهترین روش‌ها برای تبدیل DOCX به PDF در جاوا

قبل از بارگذاری، فایل‌های ورودی را اعتبارسنجی کنید تا از خطاهای خراب‌سازی DOCX جلوگیری شود.
برای اطمینان از رندر سازگار در دستگاه‌های کاربر، جاسازی فونت را فعال کنید.
برای عیب‌یابی کاهش عملکرد، زمان‌مهرهای تبدیل و تعداد رشته‌ها را ثبت کنید.
لایسنس موقت را فقط در طول توسعه استفاده کنید؛ قبل از انتشار، یک لایسنس تولیدی دریافت کنید.

نتیجه‌گیری

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

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

چگونه می‌توانم فایل‌های بزرگ DOCX را بدون تمام شدن حافظه مدیریت کنم؟
Use stream‑based conversion (setUseStream(true)) and enable multithreading. This keeps only small chunks in memory and distributes the workload across CPU cores. See the documentation for more details.

آیا امکان تبدیل فایل‌های DOCX که شامل فونت‌های سفارشی هستند وجود دارد؟
بله. SDK به‌طور خودکار فونت‌های گمشده را در PDF جاسازی می‌کند. همچنین می‌توانید در صورت نیاز، فایل‌های فونت اضافی را از طریق گزینه fontsPath فراهم کنید.

آیا می‌توانم چندین فایل DOCX را به‌صورت موازی تبدیل کنم؟
بدون شک. برای هر فایل یک کار تبدیل جداگانه ایجاد کنید و آن‌ها را در رشته‌های موازی یا یک سرویس اجرایی اجرا کنید. سرویس ابری هر درخواست را به‌صورت مستقل مدیریت می‌کند.

کجا می‌توانم پروژه‌های نمونه بیشتری پیدا کنم؟
مخزن رسمی GitHub شامل مثال‌های اضافی است: https://github.com/groupdocs-conversion-cloud/groupdocs-conversion-cloud-java. مخزن همچنین شامل اسکریپت‌های ساخت Maven و پیکربندی‌های CI است.

مراحل انجام تبدیل DOCX به PDF در Java#

تبدیل DOCX به PDF در Java - مثال کامل کد#

تبدیل سند DOCX به PDF از طریق REST API با استفاده از cURL#

نصب و راه‌اندازی در جاوا#

آموزش تبدیل DOCX به PDF در Java با GroupDocs.Conversion#

GroupDocs.Conversion ویژگی‌هایی که برای این کار مهم هستند#

کار با جریان‌ها و گزینه‌های خروجی#

بهینه‌سازی عملکرد تبدیل DOCX به PDF#

بهترین روش‌ها برای تبدیل DOCX به PDF در جاوا#

نتیجه‌گیری#

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

بیشتر بخوانید#