آموزش گام به گام تبدیل 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 API ابری.

SDK را از طریق npm نصب کنید:

npm install groupdocs-conversion-cloud

آخرین بسته را دانلود کنید و اگر نیاز به بررسی کد دارید، منبع آن را در GitHub مشاهده کنید:

دانلود GroupDocs.Conversion Cloud SDK for Node.js

پس از نصب SDK و آماده بودن اعتبارها، می‌توانید به پیاده‌سازی ادامه دهید.

تبدیل HTML به DOCX در Node.JS: راهنمای گام‌به‌گام

در ادامه یک راهنمای مختصر ارائه شده است که هر گام منطقی را نشان می‌دهد. کد منبع کامل بعداً ارائه خواهد شد.

مرحله 1: مقداردهی اولیه کلاینت 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);

مرحله ۲: بارگذاری فایل منبع 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 Generation from 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 to DOCX conversion in 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 API

اگر ترجیح می‌دهید مستقیماً با 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 مراجعه کنید.

ملاحظات عملکرد برای تبدیل محتوای HTML به DOCX

هنگام تبدیل اسناد HTML بزرگ یا پیچیده، این نکات را در نظر بگیرید:

استفاده مجدد از کلاینت API - ایجاد یک نمونه جدید از ConversionApi برای هر فایل باعث اضافه بار می‌شود.
استریم فایل‌های بزرگ HTML - به جای بارگذاری کل فایل در حافظه، از استریم‌ها (fs.createReadStream) و متد uploadFileStream SDK استفاده کنید.
محدود کردن منابع جاسازی‌شده - تصاویر یا اسکریپت‌های غیرضروری را قبل از بارگذاری از 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: مقداردهی اولیه کلاینت API تبدیل#

مرحله ۲: بارگذاری فایل منبع HTML#

مرحله 3: تنظیم گزینه‌های تبدیل#

مرحله 4: اجرای تبدیل#

مرحله 5: دانلود DOCX تولید شده#

مثال کامل کد: تولید DOCX از محتوای HTML#

اجرای تبدیل با استفاده از cURL و REST API#

پیکربندی گزینه‌ها برای تبدیل محتوای HTML به DOCX#

ملاحظات عملکرد برای تبدیل محتوای HTML به DOCX#

نتیجه‌گیری#

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

چگونه یک تبدیل HTML به DOCX را در Node.JS شروع کنم؟#

کدام گزینه‌ها را می‌توانم برای تولید DOCX از HTML تنظیم کنم؟#

آیا می‌توانم HTML که شامل CSS خارجی یا تصاویر است را تبدیل کنم؟#

آیا برای استقرارهای تولیدی به مجوز نیاز دارم؟#

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