Convertir páginas HTML enriquecidas en archivos DOCX editables es una necesidad frecuente para flujos de trabajo de generación de informes y automatización de documentos. GroupDocs.Conversion Cloud SDK for Node.js permite a los desarrolladores realizar esta conversión completamente a través de una biblioteca basada en REST. En este tutorial verás cómo configurar el SDK, escribir código Node.JS que realice la conversión de HTML a DOCX en Node.JS, usar cURL para llamar a la API y aplicar opciones de configuración para obtener resultados óptimos.
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.
- 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.
- 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"
- 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"
}
}'
- 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:
- Reutilizar el cliente API - Crear una nueva instancia
ConversionApipara cada archivo añade sobrecarga. - Transmitir archivos HTML grandes - En lugar de cargar todo el archivo en memoria, use streams (
fs.createReadStream) y el métodouploadFileStreamdel SDK. - Limitar recursos incrustados - Elimine imágenes o scripts innecesarios del HTML antes de subirlo para reducir el tiempo de procesamiento.
- 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.