تحويل ملفات PDF إلى تنسيق DOCX هو طلب شائع عند بناء تطبيقات تركز على المستندات، خاصة عندما تحتاج إلى مخرجات Word قابلة للتحرير. يوفر GroupDocs.Conversion Cloud SDK for Node.js واجهة برمجة تطبيقات قوية تجعل هذه المهمة بسيطة وقابلة للتوسع. في هذا الدليل ستشاهد عينة شفرة غير متزامنة كاملة، وتتعلم كيفية تحقيق النتيجة نفسها باستخدام استدعاءات REST عبر cURL، وتقوم بإعداد 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 الناتج.
- المصادقة والحصول على رمز وصول
استبدل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 الذي ستستخدمه في المكالمات اللاحقة.
- تحميل ملف 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
- نفّذ التحويل
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 المُولد.
- تنزيل DOCX المحول
curl -X GET "https://api.groupdocs.cloud/v1.0/storage/file/output.docx" \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-o ./local/output.docx
لمزيد من التفاصيل حول حمولة الطلب والخيارات الإضافية، راجع الوثائق الرسمية لواجهة برمجة التطبيقات.
تحليل تحويل PDF إلى DOCX في Node.JS
فيما يلي استعراض مختصر لأهم أجزاء عينة الكود غير المتزامن.
- استيراد وتكوين العميل
const GroupDocsConversionCloud = require('groupdocs-conversion-cloud');
const apiInstance = new GroupDocsConversionCloud.ConversionApi();
فئة ConversionApi (مرجع API) هي نقطة الدخول لجميع عمليات التحويل.
- تعيين بيانات اعتماد المصادقة
apiInstance.apiClient.authentications['JWT'].clientId = CLIENT_ID;
apiInstance.apiClient.authentications['JWT'].clientSecret = CLIENT_SECRET;
توفر مصادقة JWT أمانًا لكل طلب إلى خدمة السحابة.
- تحضير معلومات ملف الإدخال
const inputFileInfo = new GroupDocsConversionCloud.FileInfo();
inputFileInfo.filePath = path.normalize('input.pdf');
FileInfo يخبر API بمكان وجود ملف PDF المصدر في تخزين GroupDocs Cloud.
- تكوين خيارات DOCX‑المحددة
const docxOptions = new GroupDocsConversionCloud.DocxConvertOptions();
docxOptions.preserveOriginalFormatting = true;
DocxConvertOptions يتيح لك الاحتفاظ بالتنسيق الأصلي ومعالجة كلمات المرور إذا لزم الأمر.
- إنشاء وإرسال طلب التحويل
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
- تثبيت الحزمة
npm install groupdocs-conversion-cloud
الحزمة متاحة من سجل npm العام. راجع صفحة التحميل للحصول على تفاصيل الإصدار.
المتطلبات المسبقة
- Node.js 12 أو أعلى.
- حساب GroupDocs Cloud مع client ID و client secret.
تهيئة 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. باتباع مثال الكود غير المتزامن، وتكوين العميل بشكل صحيح، وتطبيق نصائح الأداء المذكورة أعلاه، يمكنك دمج تحويل المستندات الموثوق به في أي خدمة Node.JS. تذكر الحصول على ترخيص مناسب للاستخدام في الإنتاج؛ تفاصيل الأسعار متاحة على صفحة المنتج، ويمكن الحصول على ترخيص مؤقت من صفحة الترخيص المؤقت للتقييم.
الأسئلة المتكررة
كيف يتعامل تحويل PDF إلى DOCX في Node.JS مع التخطيطات المعقدة؟
يحاول SDK الحفاظ على التنسيق الأصلي بشكل افتراضي. يمكنك تبديلpreserveOriginalFormattingفيDocxConvertOptionsلتبادل الدقة مع السرعة. راجع مرجع API للحصول على جميع الخيارات.ما هي حدود حجم الملف لتحويل PDF إلى DOCX؟
تقبل خدمة السحابة ملفات تصل إلى 200 ميغابايت للحسابات المجانية؛ الملفات الأكبر تتطلب خطة محدثة. يتم بث التحميلات، لذا يبقى استهلاك الذاكرة على الخادم منخفضًا.هل يمكنني تحويل ملفات PDF متعددة إلى DOCX في طلب واحد؟
تقوم الواجهة البرمجية بمعالجة مستند واحد لكل طلب، ولكن يمكنك تكرار قائمة الملفات في Node.JS وتشغيل التحويلات بشكل متوازي، مع مراعاة حدود التزامن لحسابك.هل هناك طريقة لاختبار التحويل محليًا دون ترخيص مدفوع؟
نعم، يمكنك طلب ترخيص تقييم مؤقت من صفحة الترخيص المؤقت. هذا يوفر جميع الوظائف للتطوير والاختبار.
