تبدیل فایل‌های PDF به فرمت DOCX یک نیاز متداول هنگام ساخت برنامه‌های متمرکز بر اسناد است، به‌ویژه وقتی که به خروجی وورد قابل ویرایش نیاز دارید. GroupDocs.Conversion Cloud SDK for Node.js یک API قدرتمند ارائه می‌دهد که این کار را ساده و مقیاس‌پذیر می‌کند. در این راهنما، نمونه کد کامل به صورت ناهمزمان را خواهید دید، یاد می‌گیرید چگونه همان نتیجه را با درخواست‌های cURL REST به دست آورید، SDK را تنظیم کنید و توصیه‌های بهترین روش‌ها را برای تبدیل‌های قابل اطمینان اعمال کنید.

مثال کامل کد: تبدیل ناهمزمان PDF به DOCX در Node.JS

این مثال نشان می‌دهد که چگونه می‌توان تبدیل ناهمزمان PDF به DOCX را با استفاده از GroupDocs.Conversion Cloud SDK for Node.js انجام داد.

// PDF to DOCX conversion using GroupDocs.Conversion Cloud SDK for Node.js

const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const path = require('path');

// -------------------- Configuration --------------------
const CLIENT_ID = process.env.GROUPDOCS_CLIENT_ID || 'YOUR_CLIENT_ID';
const CLIENT_SECRET = process.env.GROUPDOCS_CLIENT_SECRET || 'YOUR_CLIENT_SECRET';

// Initialize API client
const apiInstance = new GroupDocsConversionCloud.ConversionApi();
apiInstance.apiClient = new GroupDocsConversionCloud.ApiClient();
apiInstance.apiClient.basePath = 'https://api.groupdocs.cloud';
apiInstance.apiClient.authentications['JWT'].clientId = CLIENT_ID;
apiInstance.apiClient.authentications['JWT'].clientSecret = CLIENT_SECRET;

// -------------------- Conversion Logic --------------------
async function convertPdfToDocx() {
    try {
        // Input file information (must already be uploaded to GroupDocs Cloud storage)
        const inputFileInfo = new GroupDocsConversionCloud.FileInfo();
        inputFileInfo.filePath = path.normalize('input.pdf'); // generic path in cloud storage

// DOCX specific conversion options (optional, shown for demonstration)
        const docxOptions = new GroupDocsConversionCloud.DocxConvertOptions();
        docxOptions.preserveOriginalFormatting = true; // keep original PDF layout as much as possible
        docxOptions.password = null; // if PDF is password protected, set it here

// Build conversion request
        const convertRequest = new GroupDocsConversionCloud.ConvertDocumentRequest();
        convertRequest.format = 'docx';
        convertRequest.fileInfo = inputFileInfo;
        convertRequest.outputPath = path.normalize('output.docx'); // result will be stored in cloud storage
        convertRequest.options = docxOptions; // attach format‑specific options

// Perform conversion (async)
        const conversionResult = await apiInstance.convertDocument(convertRequest);

// conversionResult contains the path of the generated file and other metadata
        console.log('Conversion succeeded.');
        console.log('Output file path:', conversionResult.path);
        console.log('File size (bytes):', conversionResult.size);
    } catch (error) {
        // Detailed error handling
        if (error.response && error.response.body) {
            console.error('API error:', error.response.body);
        } else {
            console.error('Unexpected error:', error.message);
        }
    }
}

// -------------------- Execution --------------------
(async () => {
    // Optional: set a timeout to avoid hanging indefinitely
    const timeoutMs = 300000; // 5 minutes
    const timeout = setTimeout(() => {
        console.error('Conversion timed out after', timeoutMs / 1000, 'seconds');
        process.exit(1);
    }, timeoutMs);

await convertPdfToDocx();

clearTimeout(timeout);
    // Graceful shutdown
    process.exit(0);
})();

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

تبدیل اسناد با استفاده از cURL و REST API

می‌توانید همان تبدیل PDF به DOCX را بدون نوشتن کد با فراخوانی مستقیم نقاط انتهایی REST سرویس GroupDocs.Conversion Cloud انجام دهید. مراحل زیر نشان می‌دهند که چگونه یک توکن دسترسی دریافت کنید، یک PDF را بارگذاری کنید، تبدیل را آغاز کنید و فایل DOCX حاصل را دانلود کنید.

  1. احراز هویت و دریافت توکن دسترسی
    YOUR_CLIENT_ID و YOUR_CLIENT_SECRET را با اعتبارهای خود جایگزین کنید.
curl -X POST "https://api.groupdocs.cloud/v1.0/oauth2/token" \
     -H "Content-Type: application/json" \
     -d '{
           "grant_type":"client_credentials",
           "client_id":"YOUR_CLIENT_ID",
           "client_secret":"YOUR_CLIENT_SECRET"
         }'

پاسخ شامل access_token است که در تماس‌های بعدی استفاده خواهید کرد.

  1. بارگذاری PDF منبع
curl -X PUT "https://api.groupdocs.cloud/v1.0/storage/file/input.pdf" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/pdf" \
     --data-binary @./local/input.pdf
  1. اجرای تبدیل
curl -X POST "https://api.groupdocs.cloud/v1.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "format":"docx",
           "fileInfo":{"filePath":"input.pdf"},
           "outputPath":"output.docx",
           "options":{"preserveOriginalFormatting":true}
         }'

پاسخ مسیر فایل DOCX تولید شده را برمی‌گرداند.

  1. دانلود DOCX تبدیل‌شده
curl -X GET "https://api.groupdocs.cloud/v1.0/storage/file/output.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o ./local/output.docx

برای جزئیات بیشتر دربارهٔ بارهای درخواست و گزینه‌های اضافی، مستندات رسمی API را ببینید.

تجزیه و تحلیل تبدیل PDF به DOCX در Node.JS

در زیر یک مرور مختصر از بخش‌های کلیدی نمونه کد ناهمزمان ارائه شده است.

  1. وارد کردن و پیکربندی کلاینت
const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const apiInstance = new GroupDocsConversionCloud.ConversionApi();

کلاس ConversionApi (API reference) نقطه ورودی برای تمام عملیات تبدیل است.

  1. تنظیم اعتبارهای احراز هویت
apiInstance.apiClient.authentications['JWT'].clientId = CLIENT_ID;
apiInstance.apiClient.authentications['JWT'].clientSecret = CLIENT_SECRET;

احراز هویت JWT هر درخواست به سرویس ابری را ایمن می‌کند.

  1. اطلاعات فایل ورودی را آماده کنید
const inputFileInfo = new GroupDocsConversionCloud.FileInfo();
inputFileInfo.filePath = path.normalize('input.pdf');

FileInfo به API می‌گوید که PDF منبع در کجا در ذخیره‌سازی GroupDocs Cloud قرار دارد.

  1. پیکربندی گزینه‌های خاص DOCX
const docxOptions = new GroupDocsConversionCloud.DocxConvertOptions();
docxOptions.preserveOriginalFormatting = true;

DocxConvertOptions به شما امکان می‌دهد تا طرح اصلی را حفظ کنید و در صورت نیاز رمزهای عبور را مدیریت کنید.

  1. ایجاد و ارسال درخواست تبدیل
const convertRequest = new GroupDocsConversionCloud.ConvertDocumentRequest();
convertRequest.format = 'docx';
convertRequest.fileInfo = inputFileInfo;
convertRequest.outputPath = path.normalize('output.docx');
convertRequest.options = docxOptions;
const conversionResult = await apiInstance.convertDocument(convertRequest);

متد convertDocument تبدیل واقعی را انجام می‌دهد و متادیتاهایی مانند مسیر خروجی و اندازه فایل را برمی‌گرداند.

نصب و پیکربندی GroupDocs.Conversion Cloud SDK for Node.JS

  1. نصب بسته
npm install groupdocs-conversion-cloud

این بسته از رجیستری عمومی npm در دسترس است. برای جزئیات نسخه، صفحه صفحه دانلود را ببینید.

  1. پیش‌نیازها

    • Node.js 12 یا بالاتر.
    • یک حساب GroupDocs Cloud با client ID و client secret.
  2. SDK را در پروژه خود مقداردهی اولیه کنید (بخش استخراج شده از مثال کامل)

const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const apiInstance = new GroupDocsConversionCloud.ConversionApi();
apiInstance.apiClient.basePath = 'https://api.groupdocs.cloud';

اگر از نقطه انتهایی منطقه‌ای استفاده می‌کنید، basePath را تنظیم کنید.

بهترین روش‌ها برای تبدیل اسناد با عملکرد بالا

  • استفاده مجدد از کلاینت API به جای ایجاد یک نمونه جدید برای هر تبدیل؛ این کار بار احراز هویت را کاهش می‌دهد.
  • فعال‌سازی بارگذاری استریمینگ برای PDFهای بزرگ تا از بارگذاری کل فایل در حافظه جلوگیری شود.
  • تنظیم زمان‌سنجی معقول (مثلاً 5 دقیقه) برای جلوگیری از گیر کردن کارها در حالی که هنوز امکان تکمیل اسناد پیچیده وجود دارد.
  • حفظ قالب‌بندی اصلی فقط در صورت نیاز؛ غیرفعال‌سازی آن می‌تواند سرعت تبدیل را برای PDFهای متنی ساده افزایش دهد.
  • نظارت بر محدودیت‌های استفاده از API در داشبورد حساب GroupDocs خود برای جلوگیری از محدود شدن در حین عملیات دسته‌ای.

نتیجه‌گیری

GroupDocs.Conversion Cloud SDK for Node.js تبدیل PDF به DOCX را به‌صورت ساده انجام می‌دهد، چه ترجیح دهید از یک کتابخانه کامل استفاده کنید و چه تماس‌های مستقیم REST با cURL. با دنبال کردن نمونه کد async، پیکربندی صحیح کلاینت و اعمال نکات عملکردی ذکر شده، می‌توانید تبدیل اسناد قابل اعتماد را در هر سرویس Node.JS یکپارچه کنید. به‌خاطر داشته باشید که برای استفاده در محیط تولید یک لایسنس مناسب تهیه کنید؛ جزئیات قیمت‌گذاری در صفحه محصول موجود است و می‌توانید برای ارزیابی یک لایسنس موقت را از صفحه لایسنس موقت دریافت کنید.

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

  • تبدیل PDF به DOCX در Node.JS چطور طرح‌های پیچیده را مدیریت می‌کند؟
    SDK به‌طور پیش‌فرض سعی می‌کند قالب‌بندی اصلی را حفظ کند. می‌توانید preserveOriginalFormatting را در DocxConvertOptions تغییر دهید تا بین دقت و سرعت تعادل برقرار کنید. برای تمام گزینه‌ها به API reference مراجعه کنید.

  • حدود اندازه فایل برای تبدیل PDF به DOCX چیست؟
    سرویس ابری فایل‌ها را تا 200 مگابایت برای حساب‌های رایگان می‌پذیرد؛ فایل‌های بزرگ‌تر به برنامه ارتقا یافته نیاز دارند. بارگذاری‌ها به صورت جریان (stream) انجام می‌شود، بنابراین مصرف حافظه در سرور شما کم می‌ماند.

  • آیا می‌توانم چندین PDF را در یک درخواست به DOCX تبدیل کنم؟
    API یک سند را در هر درخواست پردازش می‌کند، اما می‌توانید در Node.JS بر روی لیستی از فایل‌ها حلقه بزنید و تبدیل‌ها را به صورت موازی اجرا کنید، به شرطی که محدودیت‌های همزمانی حساب کاربری خود را رعایت کنید.

  • آیا راهی برای تست تبدیل به صورت محلی بدون داشتن لایسنس پولی وجود دارد؟
    بله، می‌توانید یک لایسنس ارزیابی موقت از صفحه لایسنس موقت درخواست کنید. این امکان تمام عملکردها را برای توسعه و تست فراهم می‌کند.

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