دليل خطوة بخطوة لتحويل HTML إلى DOCX في Node.JS

تحويل صفحات HTML الغنية إلى ملفات DOCX قابلة للتحرير هو حاجة متكررة في تدفقات عمل التقارير وأتمتة المستندات. يتيح GroupDocs.Conversion Cloud SDK for Node.js للمطورين تنفيذ هذا التحويل بالكامل عبر مكتبة تعتمد على REST. في هذا البرنامج التعليمي ستتعرف على كيفية إعداد SDK، كتابة كود Node.JS الذي يقوم بتحويل HTML إلى DOCX في Node.JS، استخدام cURL لاستدعاء API، وتطبيق خيارات التكوين للحصول على أفضل النتائج.

المتطلبات والإعداد

قبل أن تبدأ، تأكد من أن لديك ما يلي:

Node.js 14 أو أحدث مثبت على جهاز التطوير الخاص بك.
حساب GroupDocs.Conversion Cloud نشط (يمكنك التسجيل للحصول على نسخة تجريبية مجانية في صفحة المنتج).
Client ID و Client Secret الخاصين بك من لوحة تحكم GroupDocs Cloud.
اتصال بالإنترنت لاستدعاء واجهة برمجة التطبيقات السحابية REST.

قم بتثبيت SDK عبر npm:

npm install groupdocs-conversion-cloud

قم بتنزيل أحدث حزمة واطلع على المصدر على GitHub إذا كنت بحاجة إلى استكشاف الشيفرة:

تحميل GroupDocs.Conversion Cloud SDK for Node.js

مع تثبيت SDK وإعداد الاعتمادات، يمكنك المتابعة إلى التنفيذ.

تحويل HTML إلى DOCX في Node.JS: دليل خطوة بخطوة

فيما يلي دليل مختصر يوضح كل خطوة منطقية. يتم توفير الشيفرة المصدرية الكاملة لاحقًا.

الخطوة 1: تهيئة عميل Conversion API

إنشاء مثيل من ConversionApi وتكوين المصادقة.

const { ConversionApi, Configuration } = require('groupdocs-conversion-cloud');

const config = new Configuration({
    clientId: 'YOUR_CLIENT_ID',
    clientSecret: 'YOUR_CLIENT_SECRET'
});

const conversionApi = new ConversionApi(config);

الخطوة 2: تحميل ملف مصدر HTML

قم بتحميل ملف HTML الذي تريد تحويله. تُرجع الـ API معرف الملف الذي ستستخدمه للتحويل.

const fs = require('fs');
const path = require('path');

const htmlPath = path.resolve(__dirname, 'sample.html');
const fileBytes = fs.readFileSync(htmlPath);

const uploadResponse = await conversionApi.uploadFile({
    file: fileBytes,
    fileName: 'sample.html'
});
const sourceFileId = uploadResponse.id;

الخطوة 3: ضبط خيارات التحويل

قم بتكوين أي خيارات خاصة بـ DOCX، مثل تضمين الخطوط أو ضبط هوامش الصفحة. توضح هذه الخطوة تخصيص إنشاء DOCX من HTML.

const convertSettings = {
    outputFormat: 'DOCX',
    options: {
        embedFonts: true,
        pageSize: 'A4',
        marginTop: 20,
        marginBottom: 20,
        marginLeft: 15,
        marginRight: 15
    }
};

الخطوة 4: تنفيذ التحويل

استدعِ طريقة convert مع معرف ملف المصدر والإعدادات المحددة أعلاه.

const convertResponse = await conversionApi.convert({
    fileId: sourceFileId,
    convertSettings: convertSettings
});
const docxFileId = convertResponse.id;

الخطوة 5: تنزيل ملف DOCX الناتج

استرجع ملف DOCX المُنشأ واحفظه محليًا.

const docxData = await conversionApi.downloadFile({ fileId: docxFileId });
fs.writeFileSync(path.resolve(__dirname, 'output.docx'), docxData);
console.log('DOCX file saved as output.docx');

الخطوات أعلاه توضح سير عمل كامل تحويل HTML إلى DOCX في Node.JS باستخدام GroupDocs.Conversion Cloud SDK.

مثال كامل للكود: إنشاء DOCX من محتوى HTML

البرنامج التالي يجمع جميع الأجزاء معًا في نص برمجي واحد قابل للتنفيذ.

// Full working example for HTML to DOCX conversion using GroupDocs.Conversion Cloud SDK for Node.js

const { ConversionApi, Configuration } = require('groupdocs-conversion-cloud');
const fs = require('fs');
const path = require('path');

async function convertHtmlToDocx() {
    // 1. Configure the API client
    const config = new Configuration({
        clientId: 'YOUR_CLIENT_ID',
        clientSecret: 'YOUR_CLIENT_SECRET'
    });
    const conversionApi = new ConversionApi(config);

// 2. Read the HTML file
    const htmlPath = path.resolve(__dirname, 'sample.html');
    const htmlBytes = fs.readFileSync(htmlPath);

// 3. Upload the HTML file
    const uploadResult = await conversionApi.uploadFile({
        file: htmlBytes,
        fileName: 'sample.html'
    });
    const sourceFileId = uploadResult.id;

// 4. Define conversion settings
    const convertSettings = {
        outputFormat: 'DOCX',
        options: {
            embedFonts: true,
            pageSize: 'A4',
            marginTop: 20,
            marginBottom: 20,
            marginLeft: 15,
            marginRight: 15
        }
    };

// 5. Perform the conversion
    const convertResult = await conversionApi.convert({
        fileId: sourceFileId,
        convertSettings: convertSettings
    });
    const docxFileId = convertResult.id;

// 6. Download the DOCX file
    const docxBytes = await conversionApi.downloadFile({ fileId: docxFileId });
    const outputPath = path.resolve(__dirname, 'output.docx');
    fs.writeFileSync(outputPath, docxBytes);
    console.log(`Conversion successful. DOCX saved to ${outputPath}`);
}

// Execute the conversion
convertHtmlToDocx().catch(err => {
    console.error('Conversion failed:', err);
});

ملاحظة: مثال الشيفرة هذا يوضح الوظيفة الأساسية. قبل استخدامه في مشروعك، تأكد من تحديث مسارات الملفات (sample.html, output.docx)، والتحقق من تثبيت جميع الاعتمادات المطلوبة بشكل صحيح، واختبارها بدقة في بيئة التطوير الخاصة بك. إذا واجهت أي مشاكل، يرجى الرجوع إلى الوثائق الرسمية أو التواصل مع فريق الدعم للحصول على المساعدة.

تنفيذ التحويل عبر cURL وواجهة برمجة التطبيقات REST

إذا كنت تفضل العمل مباشرةً عبر HTTP، فإن أوامر cURL التالية تقوم بنفس التحويل.

الحصول على رمز الوصول

استبدل YOUR_CLIENT_ID و YOUR_CLIENT_SECRET ببيانات الاعتماد الخاصة بك.

curl -X POST "https://api.groupdocs.cloud/v2.0/oauth2/token" \
     -H "Content-Type: application/x-www-form-urlencoded" \
     -d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"

تحتوي الاستجابة على access_token.

تحميل ملف HTML

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

ابدأ التحويل

curl -X POST "https://api.groupdocs.cloud/v2.0/conversion/convert" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
           "sourceFilePath": "sample.html",
           "outputFilePath": "output.docx",
           "outputFormat": "DOCX",
           "options": {
               "embedFonts": true,
               "pageSize": "A4"
           }
         }'

تحميل ملف DOCX المحول

curl -X GET "https://api.groupdocs.cloud/v2.0/storage/files/output.docx" \
     -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
     -o output.docx

للحصول على قائمة كاملة بالمعلمات، راجع وثائق API الرسمية.

تكوين الخيارات لتحويل محتوى HTML إلى DOCX

يتيح SDK عدة خصائص تسمح لك بضبط الإخراج بدقة:

embedFonts - يدمج جميع الخطوط المشار إليها في ملف DOCX، مما يضمن الدقة البصرية.
pageSize - يحدد حجم الصفحة (A4, Letter, إلخ).
marginTop / marginBottom / marginLeft / marginRight - يضبط هوامش الصفحة بالنقاط.

مثال على تطبيق هذه الخيارات:

const convertSettings = {
    outputFormat: 'DOCX',
    options: {
        embedFonts: true,
        pageSize: 'Letter',
        marginTop: 30,
        marginBottom: 30,
        marginLeft: 20,
        marginRight: 20
    }
};

راجع فئة ConversionOptions class للحصول على القائمة الكاملة.

اعتبارات الأداء لتحويل محتوى HTML إلى DOCX

عند تحويل مستندات HTML الكبيرة أو المعقدة، احرص على مراعاة هذه النصائح:

إعادة استخدام عميل API - إنشاء نسخة جديدة من ConversionApi لكل ملف يضيف عبئًا.
تدفق ملفات HTML الكبيرة - بدلاً من تحميل الملف بالكامل في الذاكرة، استخدم التدفقات (fs.createReadStream) وطريقة SDK uploadFileStream.
تقليل الموارد المضمنة - احذف الصور أو السكريبتات غير الضرورية من HTML قبل الرفع لتقليل وقت المعالجة.
تحويلات دفعة - عالج الملفات بشكل متسلسل في حلقة، لكن احترم حدود معدل طلبات API لتجنب التقييد.

تطبيق هذه الممارسات يساعد في الحفاظ على انخفاض الكمون واستهلاك الذاكرة المعتدل.

الخلاصة

تحويل HTML إلى DOCX في Node.JS يصبح بسيطًا مع GroupDocs.Conversion Cloud SDK for Node.js. باتباع الخطوات المذكورة أعلاه، يمكنك دمج إنشاء DOCX موثوق من HTML في أي تطبيق من جانب الخادم، وتخصيص المخرجات، وتحسين الأداء للعبء الكبير. تذكر الحصول على ترخيص مناسب للاستخدام في الإنتاج؛ يمكنك شراء اشتراك أو الحصول على ترخيص مؤقت من صفحة الترخيص المؤقت. برمجة سعيدة!

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

كيف أبدأ تحويل HTML إلى DOCX في Node.JS؟

استخدم SDK لإنشاء عميل ConversionApi، قم بتحميل ملف HTML الخاص بك، حدد خيارات التحويل المطلوبة، واستدعِ طريقة convert. العملية غير متزامنة بالكامل وتعيد معرف ملف DOCX للتنزيل.

ما هي الخيارات التي يمكنني تعديلها لتوليد DOCX من HTML؟

كائن ConversionOptions يتيح لك تضمين الخطوط، اختيار حجم الصفحة، ضبط الهوامش، والتحكم في معالجة الصور. راجع مرجع API لجميع الإعدادات المتاحة.

هل يمكنني تحويل HTML يحتوي على CSS خارجي أو صور؟

نعم. قم بتحميل أي موارد مرجعية (CSS، صور) إلى نفس مجلد التخزين قبل بدء التحويل، وسيقوم SDK بحل الروابط أثناء المعالجة.

هل أحتاج إلى ترخيص للنشر في بيئة الإنتاج؟

يتطلب الترخيص الصالح للإنتاج. يمكنك الحصول على ترخيص مؤقت للاختبار من صفحة الترخيص المؤقتة وشراء اشتراك كامل عندما تكون جاهزًا للبدء.

المتطلبات والإعداد#

تحويل HTML إلى DOCX في Node.JS: دليل خطوة بخطوة#

الخطوة 1: تهيئة عميل Conversion API#

الخطوة 2: تحميل ملف مصدر HTML#

الخطوة 3: ضبط خيارات التحويل#

الخطوة 4: تنفيذ التحويل#

الخطوة 5: تنزيل ملف DOCX الناتج#

مثال كامل للكود: إنشاء DOCX من محتوى HTML#

تنفيذ التحويل عبر cURL وواجهة برمجة التطبيقات REST#

تكوين الخيارات لتحويل محتوى HTML إلى DOCX#

اعتبارات الأداء لتحويل محتوى HTML إلى DOCX#

الخلاصة#

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

كيف أبدأ تحويل HTML إلى DOCX في Node.JS؟#

ما هي الخيارات التي يمكنني تعديلها لتوليد DOCX من HTML؟#

هل يمكنني تحويل HTML يحتوي على CSS خارجي أو صور؟#

هل أحتاج إلى ترخيص للنشر في بيئة الإنتاج؟#

اقرأ المزيد#