API JavaScript para generar documentos Word dinámicos
Biblioteca JavaScript de código abierto para crear documentos Word dinámicos con Node.js y aplicaciones basadas en el navegador.
¿Qué es Docx-templates?
Docx-Templates es una biblioteca JavaScript de código abierto que permite a los desarrolladores de software generar documentos dinámicos de Microsoft Word (.docx) utilizando plantillas predefinidas. En lugar de crear manualmente documentos Word de forma programática, los desarrolladores pueden diseñar plantillas en Microsoft Word e inyectar datos dinámicos mediante comandos incrustados. Esta biblioteca funciona tanto en entornos Node.js como en navegadores, lo que la hace muy versátil para aplicaciones web modernas y del lado del servidor. Procesa archivos DOCX analizando su estructura XML interna y reemplazando los comandos de plantilla con datos reales en tiempo de ejecución.
La biblioteca Docx-Templates es una herramienta potente y de código abierto diseñada tanto para entornos Node.js como de navegador. La principal ventaja de la biblioteca es la separación del diseño y la lógica. Los usuarios no técnicos pueden diseñar el diseño y el estilo en Word, mientras los desarrolladores se centran en inyectar los datos. Soporta lógica compleja como bucles, formato condicional e incluso la ejecución de fragmentos de JavaScript directamente dentro del documento. Esto la convierte en una solución ideal para los desarrolladores que necesitan generar informes de alta fidelidad sin luchar contra XML o herramientas de diseño propietarias.
Comenzando con Docx-templates
La forma recomendada de instalar la biblioteca Docx-templates es a través de npm. Por favor, use el siguiente comando para una instalación sin problemas
Instalar Docx-Templates vía NPM
$ npm install docx-templates Instalar Docx-Templates vía Yarn/strong>
$ yarn add docx-templates Generación de documentos basada en plantillas mediante API JS
La biblioteca de código abierto Docx-Templates permite a los desarrolladores de software diseñar documentos en Word e inyectar datos de forma dinámica usando comandos simples. Este enfoque separa la presentación de la lógica, haciendo que las plantillas sean fáciles de gestionar y actualizar sin cambiar el código. Puedes acceder directamente a las propiedades de tu objeto de datos o incluso ejecutar expresiones simples. Por ejemplo, para insertar un nombre completo, tu plantilla se vería así: {firstName} {surname}. La biblioteca evalúa el código y lo reemplaza sin problemas.
¿Cómo crear documentos Word dinámicamente dentro de aplicaciones JavaScript?
import createReport from 'docx-templates';
import fs from 'fs';
const template = fs.readFileSync('template.docx');
const report = await createReport({
template,
data: { name: 'John', surname: 'Doe' },
});
fs.writeFileSync('output.docx', report);
Inyección dinámica de imágenes mediante JavaScript
Más allá del texto, la biblioteca de código abierto Docx-Templates puede inyectar imágenes al instante. Esto incluye archivos locales, imágenes desde una URL o incluso códigos QR generados programáticamente. Puedes controlar el tamaño de la imagen y su ubicación. Esta característica es un cambio radical para crear credenciales de identificación, catálogos de productos o informes que requieren gráficos dinámicos y evidencia visual. Aquí tienes un ejemplo sencillo que demuestra cómo insertar una imagen en documentos de Word mediante la API de JavaScript.
¿Cómo insertar una imagen al vuelo dentro de documentos Word mediante la API de JavaScript?
const buffer = await createReport({
template,
data: {
userAvatar: async () => {
const resp = await fetch('https://example.com/photo.png');
return { width: 3, height: 3, data: await resp.arrayBuffer(), extension: '.png' };
}
},
});
// In Word: {IMAGE userAvatar()}
Bucles potentes (FOR/END-FOR)
Manejar listas de datos es sencillo con el comando FOR. Esta característica le permite iterar sobre matrices para generar filas de tabla, listas o incluso secciones completas de un documento. La biblioteca Docx-Templates ha incluido soporte para bucles anidados, lo que le permite representar estructuras de datos jerárquicas complejas, como una lista de departamentos con sus respectivos empleados, todo mientras se mantiene el estilo original de Word. El siguiente ejemplo de código muestra cómo lograrlo.
¿Cómo aplicar bucles avanzados dentro de aplicaciones JavaScript?
const buffer = await createReport({
template,
data: {
projects: [
{ name: 'SEO Optimization', status: 'Completed' },
{ name: 'API Integration', status: 'In Progress' }
]
},
});
/* In Word:
{FOR project IN projects}
Project: {project.name} - Status: {project.status}
{END-FOR}
*/
Contexto JavaScript personalizado (EXEC)
Una de las características más avanzadas de la biblioteca Docx-Templates es la capacidad de ejecutar fragmentos arbitrarios de JavaScript usando el comando EXEC (o !). Al proporcionar un additionalJsContext, puede exponer funciones auxiliares personalizadas a la plantilla. Esto permite que la plantilla realice cálculos, formatee fechas o manipule cadenas internamente sin necesidad de preprocesar cada pieza de datos en la lógica principal de su aplicación.
