Como converter macros VBA do Word para Office Scripts e obter compatibilidade na nuvem

Você tem um conjunto de macros VBA no Word que automatizam tarefas repetitivas, mas elas param de funcionar quando você abre o documento no Word para a web ou o compartilha com usuários que têm apenas acesso na nuvem. As macros VBA são executadas apenas na versão desktop do Word, não no Office baseado em navegador. Os Office Scripts são a linguagem de automação nativa da nuvem que funciona no Excel, Word e outros aplicativos web do Microsoft 365. Este artigo explica as principais diferenças entre VBA e Office Scripts, fornece um método passo a passo para reescrever suas macros e lista armadilhas comuns de conversão a serem evitadas.

Por que as macros VBA falham na nuvem e o que os Office Scripts oferecem como alternativa

VBA (Visual Basic for Applications) é uma linguagem baseada em COM que requer o aplicativo Word desktop completo para ser executada. Quando você abre um documento do Word em um navegador, o runtime VBA está ausente, então as macros são ignoradas ou causam um erro. Os Office Scripts, introduzidos em 2020, são construídos em TypeScript e executados em um ambiente isolado dentro do Microsoft 365. Eles podem ser acionados manualmente, por um botão ou por meio de fluxos do Power Automate. Os Office Scripts oferecem suporte ao Word, Excel e PowerPoint na web. Eles não podem interagir com o sistema de arquivos, bancos de dados externos ou APIs do Windows como o VBA pode. Entender esses limites ajuda você a decidir quais macros valem a pena converter e quais devem permanecer apenas no desktop.

A diferença central é o ambiente de execução. O VBA é executado dentro do processo do Windows e tem acesso total ao modelo de objeto do aplicativo host. Os Office Scripts são executados em um mecanismo JavaScript separado e se comunicam com o aplicativo por meio de uma API restrita. Por exemplo, o método Documents.Open do VBA não tem equivalente direto no Office Scripts; você só pode trabalhar com o documento que já está aberto. Caixas de diálogo de arquivo, caixas de mensagem e formulários de usuário não estão disponíveis. Você deve substituí-los por parâmetros de script ou uma experiência simples de painel de tarefas.

Quando a conversão faz sentido

Converta macros que formatam texto, aplicam estilos, inserem cabeçalhos ou geram tabelas. Essas tarefas mapeiam bem para a API do Office Scripts. Evite converter macros que dependem de comandos do shell do Windows, controles ActiveX ou DLLs de terceiros. Elas nunca funcionarão na nuvem.

Passos para reescrever uma macro VBA do Word como um Office Script

Siga estes passos para converter uma macro VBA simples que aplica formatação em negrito e um estilo de título ao texto selecionado. O mesmo padrão se aplica a scripts mais complexos.

1. Abra seu documento no Word para a web
   Entre no Office.com e abra o documento do Word que contém sua macro VBA. A macro não será executada, mas você pode visualizar o código baixando o documento e abrindo-o no aplicativo desktop. Copie o código VBA para um arquivo de texto para referência.
2. Abra a guia Automatizar e crie um novo script
   No Word para a web, clique na guia Automatizar na faixa de opções. Clique em Novo Script. O Editor de Código abre com um script de exemplo. Exclua o código de exemplo.
3. Escreva o Office Script usando sintaxe TypeScript
   Substitua a lógica VBA linha por linha. Por exemplo, se sua macro VBA for:
   Sub BoldHeader()
Selection.Font.Bold = True
Selection.Style = ActiveDocument.Styles("Heading 1")
End Sub
   O Office Script equivalente é:
   function main(workbook: WordScript.Word) {
let selection = workbook.getSelection();
let range = selection.getRange();
range.getFont().setBold(true);
let headingStyle = workbook.getStyles().getItem("Heading 1");
range.setStyle(headingStyle);
}
   Digite isso no Editor de Código. Observe que a função deve ser nomeada main e recebe um parâmetro WordScript.Word.
4. Teste o script no navegador
   Clique no botão Executar no Editor de Código. O script é executado no documento ativo. Verifique se o texto selecionado está em negrito e formatado como Título 1. Se aparecerem erros, leia a mensagem de erro; geralmente aponta para uma propriedade ausente ou nome de método incorreto.
5. Salve o script no documento
   Após testar, clique em Salvar. O script se torna parte do documento. Você pode renomeá-lo clicando no nome do script na parte superior do Editor de Código. Outros usuários que abrirem o documento no Word para a web verão o script na guia Automatizar.
6. Adicione um botão de script à faixa de opções (opcional)
   Para facilitar a execução do script, clique nos três pontos ao lado do nome do script no painel Automatizar e selecione Adicionar à faixa de opções. Um botão aparece na guia Automatizar para todos os usuários do documento.

Mapeando padrões comuns de VBA para Office Scripts

Use esta referência rápida para conversões frequentes:

• VBA: Selection.Text → Office Scripts: range.getText()
• VBA: ActiveDocument.Paragraphs.Add → Office Scripts: workbook.getBody().insertParagraph(paragraphLocation.Start)
• VBA: Selection.Find.Execute FindText:="hello" → Office Scripts: range.search("hello") (retorna um objeto SearchResult)
• VBA: MsgBox "Done" → Office Scripts: console.log("Done") (a saída aparece no console do Editor de Código)

Problemas comuns de conversão e como resolvê-los

Office Scripts não podem abrir ou fechar documentos

As macros VBA geralmente abrem um segundo documento, copiam dados e o fecham. Os Office Scripts só podem trabalhar com o documento que já está aberto no navegador. Para contornar isso, abra ambos os documentos em guias separadas do navegador e use o Power Automate para passar dados entre eles. Alternativamente, armazene os dados em uma lista do SharePoint e leia-os a partir do script.

Prompts de usuário e caixas de entrada estão ausentes

InputBox e MsgBox do VBA não estão disponíveis. Substitua-os por parâmetros de script. Ao executar um script da guia Automatizar, você pode adicionar parâmetros no Editor de Código. O usuário é solicitado a inserir valores antes da execução do script. Por exemplo, declare function main(workbook: WordScript.Word, userName: string) e o usuário verá um campo de texto.

Loop por todos os parágrafos causa problemas de desempenho

Os Office Scripts são executados em um ambiente isolado do navegador com limites de memória. Percorrer milhares de parágrafos um por um pode causar tempo limite. Use operações em lote como range.getText() e processe a string em JavaScript, depois aplique a formatação a todo o intervalo. Evite loops aninhados se possível.

Macro VBA vs Office Script: Principais diferenças para automação

Item	Macro VBA	Office Script
Ambiente de execução	Word desktop (apenas Windows)	Word para a web (qualquer navegador)
Linguagem de programação	Visual Basic for Applications	TypeScript (superconjunto de JavaScript)
Acesso ao sistema de arquivos	Leitura/gravação total	Nenhum
Métodos de entrada do usuário	MsgBox, InputBox, UserForms	Parâmetros de script, console.log
Compartilhamento e armazenamento	Incorporado em .docm ou .dotm	Armazenado dentro do documento na nuvem
Opções de acionamento	Botão, atalho de teclado, evento	Botão na guia Automatizar, fluxo do Power Automate

Agora você pode converter suas macros VBA mais usadas em Office Scripts que funcionam no Word para a web. Comece com uma macro simples que formata texto ou insere uma tabela. Após testar, adicione um botão de script à guia Automatizar para que sua equipe possa executá-lo sem alternar para o aplicativo desktop. Para macros que exigem acesso a arquivos ou formulários de usuário, mantenha-as na versão desktop e, em vez disso, crie um fluxo do Power Automate que chame o script quando um documento for modificado no SharePoint.