Requisitos previos y configuración

Antes de comenzar, asegúrese de tener lo siguiente:

• Node.js 14 o posterior instalado en su máquina de desarrollo.
• Una cuenta activa de GroupDocs.Conversion Cloud (puede registrarse para una prueba gratuita en la página del producto).
• Su Client ID y Client Secret del panel de GroupDocs Cloud.
• Conectividad a Internet para llamar a la API REST de la nube.

Instale el SDK mediante npm:

npm install groupdocs-conversion-cloud

Descargue el paquete más reciente y vea el código fuente en GitHub si necesita explorar el código:

Descargar GroupDocs.Conversion Cloud SDK for Node.js

Con el SDK instalado y las credenciales listas, puedes pasar a la implementación.

Conversión de HTML a DOCX en Node.JS: Guía paso a paso

A continuación se muestra una guía concisa que muestra cada paso lógico. El código fuente completo se proporciona más adelante.

Paso 1: Inicializar el cliente de la API de conversión

Cree una instancia de ConversionApi y configure la autenticación.

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

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

const conversionApi = new ConversionApi(config);

Paso 2: Cargar el archivo fuente HTML

Cargue el archivo HTML que desea convertir. La API devuelve un identificador de archivo que utilizará para la conversión.

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;

Paso 3: Establecer opciones de conversión

Configure cualquier opción específica de DOCX, como incrustar fuentes o establecer márgenes de página. Este paso demuestra la personalización de Generación de DOCX desde HTML.

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

Paso 4: Ejecutar la conversión

Llame al método convert con el ID del archivo de origen y la configuración definida arriba.

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

Paso 5: Descargar el DOCX resultante

Recupere el archivo DOCX generado y guárdelo localmente.

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

Los pasos anteriores ilustran un flujo de trabajo completo de conversión de HTML a DOCX en Node.JS utilizando el GroupDocs.Conversion Cloud SDK.

Ejemplo de código completo: Generar DOCX a partir de contenido HTML

El siguiente programa reúne todas las piezas en un único script ejecutable.

// 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: Este ejemplo de código demuestra la funcionalidad principal. Antes de usarlo en su proyecto, asegúrese de actualizar las rutas de los archivos (sample.html, output.docx), verifique que todas las dependencias requeridas estén correctamente instaladas y pruebe exhaustivamente en su entorno de desarrollo. Si encuentra algún problema, consulte la documentación oficial o comuníquese con el equipo de soporte para obtener ayuda.

Ejecutando la conversión mediante cURL y la API REST

Si prefiere trabajar directamente con HTTP, los siguientes comandos cURL realizan la misma conversión.

1. Obtener un token de acceso

Reemplace YOUR_CLIENT_ID y YOUR_CLIENT_SECRET con sus credenciales.

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 respuesta contiene access_token.

2. Cargar el archivo 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. Inicie la conversión

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. Descargar el DOCX convertido

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

Para obtener una lista completa de los parámetros, consulte la documentación oficial de la API.

Configuración de opciones para la conversión de contenido HTML a DOCX

El SDK expone varias propiedades que le permiten afinar la salida:

• embedFonts - Inserta todas las fuentes referenciadas en el DOCX, asegurando la fidelidad visual.
• pageSize - Establece el tamaño de página (A4, Letter, etc.).
• marginTop / marginBottom / marginLeft / marginRight - Ajusta los márgenes de la página en puntos.

Ejemplo de aplicación de estas opciones:

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

Consulte la clase ConversionOptions para obtener la lista completa.

Consideraciones de rendimiento para la conversión de contenido HTML a DOCX

Al convertir documentos HTML grandes o complejos, tenga en cuenta estos consejos:

1. Reutilizar el cliente API - Crear una nueva instancia ConversionApi para cada archivo añade sobrecarga.
2. Transmitir archivos HTML grandes - En lugar de cargar todo el archivo en memoria, use streams (fs.createReadStream) y el método uploadFileStream del SDK.
3. Limitar recursos incrustados - Elimine imágenes o scripts innecesarios del HTML antes de subirlo para reducir el tiempo de procesamiento.
4. Conversiones por lotes - Procese los archivos secuencialmente en un bucle, pero respete los límites de velocidad de la API para evitar la limitación.

Aplicar estas prácticas ayuda a mantener una latencia baja y un consumo de memoria moderado.

Conclusión

La conversión de HTML a DOCX en Node.JS se vuelve sencilla con el GroupDocs.Conversion Cloud SDK for Node.js. Siguiendo los pasos anteriores, puedes integrar la generación confiable de DOCX a partir de HTML en cualquier aplicación del lado del servidor, personalizar la salida y optimizar el rendimiento para cargas de trabajo grandes. Recuerda adquirir una licencia adecuada para uso en producción; puedes comprar una suscripción u obtener una licencia temporal desde la página de licencia temporal. ¡Feliz codificación!

Preguntas frecuentes

¿Cómo inicio una conversión de HTML a DOCX en Node.JS?

Utilice el SDK para crear un cliente ConversionApi, cargue su archivo HTML, establezca las opciones de conversión deseadas y llame al método convert. El proceso es completamente asíncrono y devuelve el identificador del archivo DOCX para su descarga.

¿Qué opciones puedo ajustar para la generación de DOCX a partir de HTML?

El objeto ConversionOptions le permite incrustar fuentes, elegir el tamaño de página, establecer márgenes y controlar el manejo de imágenes. Consulte la referencia de API para ver todas las configuraciones disponibles.

¿Puedo convertir HTML que contiene CSS externo o imágenes?

Sí. Cargue los recursos referenciados (CSS, imágenes) en la misma carpeta de almacenamiento antes de iniciar la conversión, y el SDK resolverá los enlaces durante el procesamiento.

¿Necesito una licencia para implementaciones en producción?

Se requiere una licencia válida para producción. Puedes obtener una licencia temporal para pruebas desde la página de licencia temporal y comprar una suscripción completa cuando estés listo para lanzar.

Leer más

• Convertir JSON a HTML en Node.js | Conversión de JSON a página web
• Ejemplo paso a paso de conversión de CSV a PDF en Node.JS
• Tutorial paso a paso de conversión de HTML a XLSX en PHP