Покроковий посібник з конвертації 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 для Node.js

Після встановлення SDK та підготовки облікових даних ви можете перейти до реалізації.

Конвертація HTML у DOCX у Node.JS: покроковий огляд

Нижче наведено стислий покроковий огляд, який показує кожен логічний крок. Повний вихідний код надається пізніше.

Крок 1: Ініціалізувати Conversion API Client

Створіть екземпляр 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 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: Ініціалізувати Conversion API Client#

Крок 2: Завантажити HTML файл джерела#

Крок 3: Встановити параметри конвертації#

Крок 4: Виконайте конвертацію#

Крок 5: Завантажити отриманий DOCX#

Повний приклад коду: генерування DOCX з HTML‑вмісту#

Виконання конвертації за допомогою cURL та REST API#

Налаштування параметрів конвертації HTML в DOCX#

Міркування щодо продуктивності при конвертації HTML у DOCX#

Висновок#

Часті питання#

Як розпочати конвертацію HTML у DOCX у Node.JS?#

Які параметри можна налаштувати для генерації DOCX з HTML?#

Чи можу я конвертувати HTML, що містить зовнішні CSS або зображення?#

Чи потрібна ліцензія для виробничих розгортань?#

Read More#