Como Usar a API Moderna do Word com VBA Versus o Suplemento JavaScript do Office

Você precisa automatizar o Word, mas não sabe se deve usar VBA ou o novo modelo de Suplemento JavaScript do Office. As macros VBA tradicionais são executadas dentro do aplicativo Word para desktop e dependem do modelo de objeto legado. A API moderna do Word é uma interface baseada em REST que funciona no Word para web, desktop e dispositivos móveis. Este artigo compara ambas as abordagens, explica quando escolher cada uma e fornece instruções passo a passo para construir uma tarefa de automação simples com ambos os métodos.

Entendendo os Dois Modelos de Automação para o Word

O VBA faz parte do Word há décadas. Ele é executado dentro do processo do Word, tem acesso completo ao modelo de objeto Document e pode controlar todos os aspectos do aplicativo. As macros VBA são incorporadas em arquivos .docm ou .dotm e exigem a versão desktop do Word. Elas não podem ser executadas no Word para web ou em dispositivos móveis.

A API moderna do Word consiste em duas camadas: a API JavaScript do Word (Office.js) usada em Suplementos do Office e a API REST do Word acessada por meio do Microsoft Graph. Os Suplementos do Office são aplicativos web executados em um painel de tarefas ou controle de conteúdo dentro do Word. Eles funcionam no Windows, Mac, navegador e dispositivos móveis. A API REST é stateless e projetada para processamento de documentos no lado do servidor, sem um cliente Word.

Quando o VBA é a Escolha Certa

Use VBA quando precisar automatizar tarefas que exigem interação direta com a janela do aplicativo Word, como abrir caixas de diálogo, alterar configurações de impressão ou executar recursos legados como Mala Direta. O VBA também é ideal para macros pessoais ou departamentais que não precisam ser distribuídas para usuários em outras plataformas.

Quando o Suplemento JavaScript do Office é a Escolha Certa

Escolha o modelo de Suplemento JavaScript quando precisar de uma solução que funcione no Word para web, Word para Mac e Word mobile. O Suplemento é executado em um ambiente de navegador isolado e não pode acessar o sistema de arquivos local ou o registro do Windows. É melhor para aplicações de painel de tarefas que inserem conteúdo, modificam formatação ou interagem com serviços web externos.

Passos para Criar uma Automação Básica com VBA

Os passos a seguir criam uma macro VBA que insere uma tabela formatada na posição do cursor. Abra o editor VBA com Alt+F11, insira um novo módulo e cole o código.

1. Abra o Editor VBA
   Pressione Alt+F11 no Word. No Project Explorer, clique com o botão direito em Normal ou no nome do seu documento e escolha Insert > Module.
2. Escreva o Código da Macro
   No novo módulo, cole o seguinte código:
   Sub InsertTableVBA()
Dim tbl As Table
Set tbl = ActiveDocument.Tables.Add(Range:=Selection.Range, NumRows:=3, NumColumns:=4)
tbl.Borders.Enable = True
tbl.Cell(1, 1).Range.Text = "Header"
End Sub
3. Execute a Macro
   Pressione F5 enquanto o cursor estiver dentro da macro, ou feche o editor e pressione Alt+F8. Selecione InsertTableVBA e clique em Run.
4. Salve o Documento como Habilitado para Macro
   Vá em File > Save As. Escolha Word Macro-Enabled Document (.docm) na lista de tipos de arquivo.

Passos para Criar a Mesma Automação com um Suplemento JavaScript do Office

O Suplemento JavaScript requer um servidor web ou uma pasta local com um arquivo de manifesto, uma página HTML e um arquivo JavaScript. Os passos a seguir usam uma pasta local para teste.

1. Crie a Pasta do Projeto
   Crie uma pasta chamada WordAddin. Dentro dela, crie três arquivos: manifest.xml, index.html e app.js.
2. Escreva o Arquivo de Manifesto
   Em manifest.xml, cole o seguinte manifesto mínimo:
   <?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1"
xsi:type="TaskPaneApp">
<Id>12345678-1234-1234-1234-123456789abc</Id>
<Version>1.0.0.0</Version>
<ProviderName>YourName</ProviderName>
<DefaultLocale>en-US</DefaultLocale>
<DisplayName DefaultValue="Table Inserter"/>
<Description DefaultValue="Inserts a table at the cursor"/>
<Hosts><Host Name="Document"/></Hosts>
<DefaultSettings>
<SourceLocation DefaultValue="https://localhost:3000/index.html"/>
</DefaultSettings>
</OfficeApp>
3. Escreva a Página HTML
   Em index.html, cole:
   <!DOCTYPE html>
<html>
<head>
<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
<script src="app.js"></script>
</head>
<body>
<button id="insertTable">Insert Table</button>
</body>
</html>
4. Escreva a Lógica JavaScript
   Em app.js, cole:
   Office.onReady(function() {
document.getElementById('insertTable').onclick = function() {
Word.run(function(context) {
var table = context.document.body.insertTable(3, 4, Word.InsertLocation.start, [['Header','','','']]);
table.style = "Table Grid";
return context.sync();
});
};
});
5. Hospede e Carregue o Suplemento
   Execute um servidor HTTPS local (por exemplo, com Node.js e o pacote http-server) na porta 3000. No Word, vá em File > Options > Trust Center > Trust Center Settings > Trusted Add-in Catalogs. Adicione o caminho da sua pasta local e marque Show in Menu. Reinicie o Word e clique em Insert > Add-ins > My Add-ins para ver Table Inserter.

Erros Comuns e Limitações de Cada Abordagem

A Macro VBA Não Executa no Word para Web

Se você distribuir um arquivo .docm para usuários no Word para web, a macro não será executada. A versão web não suporta VBA. Converta a macro para um Suplemento JavaScript ou use o Power Automate com a API REST do Word.

O Suplemento JavaScript Não Pode Acessar Arquivos Locais

A API Office.js é executada dentro de um controle de navegador isolado. Ela não pode ler ou gravar arquivos no disco rígido local. Se você precisar importar dados de um arquivo CSV no disco, deve primeiro enviar o arquivo para um servidor web ou usar a API FileReader para ler o conteúdo do arquivo no navegador.

A Macro VBA Dispara Avisos de Segurança

Por padrão, o Word bloqueia macros de fontes não confiáveis. Os usuários veem uma barra de segurança amarela e precisam clicar em Enable Content. Para evitar isso, assine a macro com um certificado digital ou armazene o documento em um local confiável configurado em File > Options > Trust Center > Trust Center Settings > Trusted Locations.

O Suplemento JavaScript Exige HTTPS em Produção

Durante o desenvolvimento, você pode usar HTTP para testes locais. Para implantação em produção, o SourceLocation do manifesto deve usar HTTPS. Você também precisa de um certificado SSL válido. A Microsoft não permite suplementos HTTP no AppSource ou em ambientes de produção.

VBA vs Suplemento JavaScript do Office: Comparação de Recursos e Plataformas

Item	Macro VBA	Suplemento JavaScript do Office
Suporte de plataforma	Word desktop (Windows, Mac)	Word desktop, web, Mac, mobile
Implantação	Incorporado no arquivo .docm	Arquivo de manifesto hospedado em servidor web
Acesso ao modelo de objeto do Word	Modelo de objeto legado completo	API JavaScript do Word (subconjunto do modelo de objeto)
Acesso ao sistema de arquivos	Completo (via Scripting.FileSystemObject)	Nenhum (isolado)
Personalização da interface	XML da faixa de opções, caixas de diálogo personalizadas	HTML, CSS, JavaScript no painel de tarefas
Distribuição	E-mail, compartilhamento de rede	AppSource, SharePoint, catálogo interno
Modelo de segurança	Locais confiáveis, assinaturas digitais	HTTPS, validação de manifesto, permissões

As macros VBA oferecem controle total sobre o aplicativo Word para desktop, mas limitam você ao desktop Windows ou Mac. Os Suplementos JavaScript do Office sacrificam algum acesso profundo ao modelo de objeto em troca de alcance multiplataforma e uma pilha de desenvolvimento moderna baseada na web. Para novos projetos que precisam ser executados no Word para web ou em dispositivos móveis, o Suplemento JavaScript é o caminho recomendado. Para automação legada que usa recursos como Mala Direta ou controles ActiveX, o VBA continua sendo a única opção.

Agora você pode decidir qual modelo de automação atende aos requisitos do seu projeto. Comece testando uma macro VBA simples se seus usuários estiverem apenas no desktop. Se precisar de suporte para web ou dispositivos móveis, crie um Suplemento JavaScript usando a API JavaScript do Word e Office.js. Como dica avançada, explore a API REST do Word por meio do Microsoft Graph para geração de documentos no lado do servidor, onde nenhum cliente Word está instalado.