1. Produtos
  2.   Processamento de texto
  3.   Ruby
  4.   Ruby-Docx-Templater
 
  

Crie Arquivos Word Dinâmicos a partir de um Modelo via API Ruby Gratuita

Biblioteca Ruby Open Source Líder Projetada para Criar Documentos Microsoft Word (.docx) Dinâmicos a partir de Modelos Pré‑Projetados.

O que é Ruby-Docx-Templater?

Gerar documentos Microsoft Word dinâmicos (.docx) a partir de uma aplicação Ruby pode ser uma tarefa surpreendentemente complexa. Você pode precisar gerar relatórios, faturas ou cartas que usuários não‑técnicos tenham projetado. Embora existam muitas soluções, elas frequentemente exigem dependências pesadas como LibreOffice ou instalações locais do Word. Surge então o Ruby-Docx-Templater, uma gem leve que adota uma abordagem diferente. Ela permite que os usuários utilizem um arquivo .docx padrão como modelo, manipulando‑o completamente na memória para injetar seus dados. Isso faz dele uma opção rápida, segura e amigável para implantação para qualquer desenvolvedor Ruby.

No seu núcleo, a biblioteca Ruby-Docx-Templater é um motor de templating especificamente para arquivos .docx. É uma gem Ruby leve e poderosa projetada para criar documentos Microsoft Word (.docx) dinâmicos a partir de modelos pré‑desenhados. Ela funciona usando um simples sistema baseado em tags dentro de um documento Word padrão. Você cria um modelo no Word, coloca tags especiais onde deseja que o conteúdo dinâmico apareça e, então, deixa a gem substituir essas tags pelos dados reais da sua aplicação Ruby. Seu processamento em memória, suporte a estruturas de tabela complexas e preservação da formatação a tornam ideal para automação de documentos empresariais.

Previous Next

Introdução ao Ruby-Docx-Templater

A maneira recomendada de instalar Ruby-Docx-Templater é usando RubyGems. Por favor, use o comando abaixo para uma instalação tranquila.

Instale Ruby-Docx-Templater via RubyGems

 gem install ruby-docx-templater

Instale Ruby-Docx-Templater via GitHub

 git clone https://github.com/jawspeak/ruby-docx-templater.git
You can also download it directly from GitHub.

Crie Arquivo Word Docx a partir de um Modelo via Ruby

A funcionalidade mais básica do Ruby-Docx-Templater é a substituição simples de texto. Você pode colocar placeholders em qualquer lugar do seu documento Word, e a biblioteca os substituirá pelos valores reais. A beleza dessa abordagem é que a formatação é preservada. Se você tornar $COMPANY_NAME$ em negrito e vermelho no seu modelo, ele permanecerá em negrito e vermelho na saída. Isso dá total controle aos designers sobre a aparência do documento. No seu modelo Word, você define chaves usando a sintaxe $KEY$. Os sinais de dólar atuam como delimitadores, deixando claro onde as substituições devem ocorrer.

Criar um Arquivo Word Docx usando um Arquivo de Modelo via Ruby?

require 'docx_templater'

# Load your template file
doc = DocxTemplater::TemplateProcessor.new('invoice_template.docx')

# Define your data as a hash
data = {
  'COMPANY_NAME' => 'Acme Corporation',
  'INVOICE_NUMBER' => 'INV-2024-001',
  'INVOICE_DATE' => '2024-11-04',
  'CLIENT_NAME' => 'John Smith',
  'TOTAL_AMOUNT' => '$1,250.00'
}

# Render the document with your data
doc.render(data)

# Save the output
doc.save('output_invoice.docx')

Suporte a Loops de Tabelas com Múltiplas Linhas

Uma das funcionalidades mais poderosas é a capacidade de gerar tabelas dinâmicas com múltiplas linhas. Isso é essencial para criar listas itemizadas em faturas, catálogos de produtos ou qualquer relatório com dados repetidos. Você define uma região de loop na sua tabela e a biblioteca duplica tudo entre esses marcadores para cada item no seu array de dados. Você pode formatar cada célula individualmente no Word. Por exemplo, pode alinhar números à direita, tornar cabeçalhos em negrito ou aplicar fontes específicas. Toda formatação será preservada nas linhas geradas.

Como Criar um Relatório de Produto com Múltiplas Linhas em Formatos Docx via Biblioteca Ruby?

require 'docx_templater'

doc = DocxTemplater::TemplateProcessor.new('product_report.docx')

# Define items as an array of hashes
data = {
  'REPORT_TITLE' => 'Monthly Sales Report',
  'REPORT_DATE' => 'November 2024',
  'ITEMS_LIST' => [
    {
      'PRODUCT_NAME' => 'Laptop Pro 15"',
      'QUANTITY' => '5',
      'UNIT_PRICE' => '$1,200.00',
      'TOTAL' => '$6,000.00'
    },
    {
      'PRODUCT_NAME' => 'Wireless Mouse',
      'QUANTITY' => '12',
      'UNIT_PRICE' => '$25.00',
      'TOTAL' => '$300.00'
    },
    {
      'PRODUCT_NAME' => 'USB-C Cable',
      'QUANTITY' => '20',
      'UNIT_PRICE' => '$15.00',
      'TOTAL' => '$300.00'
    }
  ]
}

doc.render(data)
doc.save('output_sales_report.docx')

Processamento em Memória

A biblioteca Ruby-Docx-Templater de código aberto é muito fácil de manipular e oferece suporte ao processamento em memória dentro de aplicações Ruby. Toda a manipulação de documentos ocorre na memória, o que significa que seus dados sensíveis nunca tocam o sistema de arquivos durante o processo de templating. Isso é crucial para aplicações que lidam com informações confidenciais, como registros médicos, documentos financeiros ou dados pessoais.

Trabalhando com Word XML

Um aspecto único do Ruby-Docx-Templater é que às vezes você precisa editar manualmente o XML subjacente do seu documento Word. O Word frequentemente insere marcações de formatação que podem dividir as chaves do seu modelo, quebrando o processo de substituição. Quando você digita $CUSTOMER_NAME$ no Word, pode parecer correto na tela, mas o XML subjacente pode ter a seguinte aparência.

 Português