1. Produtos
  2.   Processamento de texto
  3.   JavaScript
  4.   Docx-templates
 
  

API JavaScript para gerar documentos Word dinâmicos

Biblioteca JavaScript de código aberto para criar documentos Word dinâmicos com Node.js e aplicações baseadas em navegador.

O que é Docx-templates?

Docx-Templates é uma biblioteca JavaScript de código aberto que permite que desenvolvedores de software gerem documentos Microsoft Word (.docx) dinâmicos usando modelos predefinidos. Em vez de construir documentos Word manualmente por programação, os desenvolvedores podem criar modelos no Microsoft Word e injetar dados dinâmicos usando comandos incorporados. Esta biblioteca funciona tanto em ambientes Node.js quanto em navegadores, tornando-a altamente versátil para aplicações web modernas e do lado do servidor. Ela processa arquivos DOCX analisando sua estrutura XML interna e substituindo os comandos do modelo por dados reais em tempo de execução.

A biblioteca Docx-Templates é uma ferramenta poderosa e de código aberto projetada tanto para ambientes Node.js quanto para navegadores. A principal vantagem da biblioteca é a separação entre design e lógica. Usuários não técnicos podem criar o layout e a estilização no Word, enquanto os desenvolvedores se concentram em injetar os dados. Ela suporta lógica complexa, como loops, formatação condicional e até a execução de trechos de JavaScript diretamente no documento. Isso a torna uma solução ideal para desenvolvedores que precisam gerar relatórios de alta fidelidade sem lidar com XML ou ferramentas de design proprietárias.

Previous Next

Começando com Docx-templates

A forma recomendada de instalar a biblioteca Docx-templates é via npm. Por favor, use o comando a seguir para uma instalação tranquila

Instalar Docx-Templates via NPM

$ npm install docx-templates

Instalar Docx-Templates via Yarn/strong>

$ yarn add docx-templates

Geração de Documentos Baseada em Modelo via API JS

A biblioteca de código aberto Docx-Templates permite que desenvolvedores de software criem documentos no Word e injetem dados dinamicamente usando comandos simples. Essa abordagem separa a apresentação da lógica, tornando os modelos fáceis de gerenciar e atualizar sem alterar o código. Você pode acessar diretamente as propriedades do seu objeto de dados ou até executar expressões simples. Por exemplo, para inserir um nome completo, seu modelo ficaria assim: {firstName} {surname}. A biblioteca avalia o código e o substitui perfeitamente.

Como criar documentos Word dinamicamente dentro de aplicativos 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);

Injeção Dinâmica de Imagens via JavaScript

Além do texto, a biblioteca de código aberto Docx-Templates pode injetar imagens em tempo real. Isso inclui arquivos locais, imagens de uma URL ou até códigos QR gerados programaticamente. Você pode controlar o tamanho da imagem e sua posição. Esse recurso é revolucionário para criar crachás de identificação, catálogos de produtos ou relatórios que exigem gráficos dinâmicos e evidências visuais. Aqui está um exemplo simples que demonstra como inserir uma imagem em documentos Word via API JavaScript.

Como inserir imagem dinamicamente em documentos Word via API 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()}

Loops Poderosos (FOR/END-FOR)

Manipular listas de dados é simples com o comando FOR. Esse recurso permite iterar sobre arrays para gerar linhas de tabela, listas ou até mesmo seções inteiras de um documento. A biblioteca Docx-Templates inclui suporte a loops aninhados, permitindo representar estruturas de dados hierárquicas complexas, como uma lista de departamentos com seus respectivos funcionários, tudo isso mantendo a formatação original do Word. O exemplo de código a seguir mostra como alcançar isso.

Como aplicar loop avançado dentro de aplicativos 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)

Um dos recursos mais avançados da biblioteca Docx-Templates é a capacidade de executar trechos arbitrários de JavaScript usando o comando EXEC (ou !). Ao fornecer um additionalJsContext, você pode expor funções auxiliares personalizadas para o modelo. Isso permite que o modelo realize cálculos, formate datas ou manipule strings internamente sem precisar pré-processar cada dado na lógica principal da sua aplicação.

 Português