Tutorial passo passo per la conversione da HTML a DOCX in Node.JS

Convertire pagine HTML ricche in file DOCX modificabili è una necessità frequente per i flussi di lavoro di reporting e automazione dei documenti. GroupDocs.Conversion Cloud SDK for Node.js consente agli sviluppatori di eseguire questa conversione interamente tramite una libreria basata su REST. In questo tutorial vedrai come configurare l’SDK, scrivere codice Node.JS che esegue la conversione da HTML a DOCX in Node.JS, utilizzare cURL per chiamare l’API e applicare opzioni di configurazione per risultati ottimali.

Prerequisiti e Configurazione

Prima di iniziare, assicurati di avere quanto segue:

• Node.js 14 o versioni successive installato sulla tua macchina di sviluppo.
• Un account attivo di GroupDocs.Conversion Cloud (puoi registrarti per una prova gratuita nella pagina del prodotto).
• Il tuo Client ID e Client Secret dalla dashboard di GroupDocs Cloud.
• Connettività Internet per chiamare l’API REST del cloud.

Installa l’SDK tramite npm:

npm install groupdocs-conversion-cloud

Scarica il pacchetto più recente e visualizza il codice sorgente su GitHub se hai bisogno di esplorare il codice:

Scarica GroupDocs.Conversion Cloud SDK for Node.js

Con l’SDK installato e le credenziali pronte, puoi passare all’implementazione.

Conversione da HTML a DOCX in Node.JS: Guida passo passo

Di seguito è una panoramica concisa che mostra ogni passaggio logico. Il codice sorgente completo è fornito più avanti.

Passo 1: Inizializza il client API di conversione

Crea un’istanza di ConversionApi e configura l’autenticazione.

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

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

const conversionApi = new ConversionApi(config);

Passo 2: Carica il file sorgente HTML

Carica il file HTML che desideri convertire. L’API restituisce un identificatore di file che utilizzerai per la conversione.

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;

Passo 3: Imposta le opzioni di conversione

Configura eventuali opzioni specifiche per DOCX, come l’incorporamento dei caratteri o l’impostazione dei margini di pagina. Questo passaggio dimostra la personalizzazione della Generazione di DOCX da HTML.

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

Passo 4: Esegui la conversione

Chiama il metodo convert con l’ID del file di origine e le impostazioni definite sopra.

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

Passo 5: Scarica il DOCX risultante

Recupera il file DOCX generato e salvalo localmente.

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

I passaggi sopra illustrano un flusso di lavoro completo conversione da HTML a DOCX in Node.JS utilizzando il GroupDocs.Conversion Cloud SDK.

Esempio di Codice Completo: Generazione di DOCX da Contenuto HTML

Il programma seguente mette tutti i componenti insieme in un unico script eseguibile.

// 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);
});

Nota: Questo esempio di codice dimostra la funzionalità principale. Prima di utilizzarlo nel tuo progetto, assicurati di aggiornare i percorsi dei file (sample.html, output.docx), verifica che tutte le dipendenze richieste siano correttamente installate e testa accuratamente nell’ambiente di sviluppo. Se riscontri problemi, consulta la documentazione ufficiale o contatta il team di supporto per assistenza.

Esecuzione della conversione tramite cURL e l’API REST

Se preferisci lavorare direttamente con HTTP, i seguenti comandi cURL eseguono la stessa conversione.

1. Ottieni un token di accesso

Sostituisci YOUR_CLIENT_ID e YOUR_CLIENT_SECRET con le tue credenziali.

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"

La risposta contiene access_token.

2. Carica il file HTML

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

3. Avvia la conversione

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"
           }
         }'

4. Scarica il DOCX convertito

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

Per un elenco completo dei parametri, consulta la documentazione ufficiale dell’API.

Configurazione delle opzioni per la conversione di contenuti HTML in DOCX

L’SDK espone diverse proprietà che consentono di regolare finemente l’output:

• embedFonts - Incorpora tutti i font referenziati nel DOCX, garantendo la fedeltà visiva.
• pageSize - Imposta la dimensione della pagina (A4, Letter, ecc.).
• marginTop / marginBottom / marginLeft / marginRight - Regola i margini della pagina in punti.

Esempio di applicazione di queste opzioni:

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

Fare riferimento alla classe ConversionOptions per l’elenco completo.

Considerazioni sulle prestazioni per la conversione di contenuti HTML in DOCX

Quando si convertono documenti HTML di grandi dimensioni o complessi, tenete presente questi consigli:

1. Riutilizzare il client API - Creare una nuova ConversionApi istanza per ogni file aggiunge overhead.
2. Trasmettere in streaming file HTML di grandi dimensioni - Invece di caricare l’intero file in memoria, usare gli stream (fs.createReadStream) e il metodo uploadFileStream dell’SDK.
3. Limitare le risorse incorporate - Rimuovere immagini o script non necessari dall’HTML prima del caricamento per ridurre i tempi di elaborazione.
4. Conversioni batch - Elaborare i file in sequenza in un ciclo, ma rispettare i limiti di velocità dell’API per evitare il throttling.

Applicare queste pratiche aiuta a mantenere bassa latenza e un consumo di memoria contenuto.

Conclusione

La conversione da HTML a DOCX in Node.JS diventa semplice con il GroupDocs.Conversion Cloud SDK for Node.js. Seguendo i passaggi descritti sopra, è possibile integrare la generazione affidabile di DOCX da HTML in qualsiasi applicazione server‑side, personalizzare l’output e ottimizzare le prestazioni per carichi di lavoro elevati. Ricorda di acquisire una licenza adeguata per l’uso in produzione; puoi acquistare un abbonamento o ottenere una licenza temporanea dalla pagina della licenza temporanea. Buon coding!

FAQs

Come avvio una conversione da HTML a DOCX in Node.JS?

Utilizza l’SDK per creare un client ConversionApi, carica il tuo file HTML, imposta le opzioni di conversione desiderate e chiama il metodo convert. Il processo è completamente asincrono e restituisce l’identificatore del file DOCX per il download.

Quali opzioni posso regolare per la generazione di DOCX da HTML?

L’oggetto ConversionOptions consente di incorporare i caratteri, scegliere la dimensione della pagina, impostare i margini e controllare la gestione delle immagini. Vedi il riferimento API per tutte le impostazioni disponibili.

Posso convertire HTML che contiene CSS esterno o immagini?

Sì. Carica tutte le risorse di riferimento (CSS, immagini) nella stessa cartella di archiviazione prima di avviare la conversione, e l’SDK risolverà i collegamenti durante l’elaborazione.

Ho bisogno di una licenza per le distribuzioni in produzione?

È necessaria una licenza valida per la produzione. È possibile ottenere una licenza temporanea per i test dalla pagina della licenza temporanea e acquistare un abbonamento completo quando si è pronti a passare in produzione.

Leggi di più

• Converti JSON in HTML in Node.js | Conversione da JSON a pagina web
• Esempio di conversione CSV in PDF passo-passo in Node.JS
• Tutorial passo-passo di conversione da HTML a XLSX in PHP