Como migrar código VBA do Word para Office Scripts e obter compatibilidade na nuvem

Se você tem macros VBA no Word que automatizam tarefas em documentos, elas funcionam apenas no aplicativo desktop. Os Office Scripts funcionam no Word para a web e em ambientes de nuvem do Microsoft 365. Este artigo explica as principais diferenças entre VBA e Office Scripts e fornece um processo de migração passo a passo. Você aprenderá a reescrever padrões comuns de VBA usando sintaxe TypeScript no editor de Office Scripts.

Por que as macros VBA não funcionam no Word para a web

As macros VBA são compiladas em código binário executado dentro do processo desktop do Word. O Word para a web é executado em um ambiente de navegador isolado que não pode executar VBA. Os Office Scripts usam TypeScript, um superconjunto tipado de JavaScript, e são executados em um runtime do lado do servidor chamado mecanismo Office Scripts. Esse mecanismo fornece um subconjunto do modelo de objeto do Word seguro para execução na nuvem.

A API do Office Scripts é assíncrona por design. Toda operação que lê ou escreve conteúdo do documento deve ser encapsulada em uma chamada Word.run() e seguida por context.sync(). O VBA, por outro lado, é síncrono e modifica o documento imediatamente. Essa diferença arquitetural é o principal motivo pelo qual você não pode simplesmente copiar código VBA para Office Scripts.

Pré-requisitos para usar Office Scripts

Você precisa de uma assinatura do Microsoft 365 que inclua Office Scripts, como Microsoft 365 Business Standard ou Enterprise E3/E5. Os Office Scripts estão disponíveis apenas no Word para a web, não no aplicativo desktop. Para acessar o editor de scripts, abra um documento no Word para a web e vá em Automate > Script > New Script.

Etapas para converter uma macro VBA em um Office Script

As etapas a seguir pressupõem que você tenha uma macro VBA funcional no aplicativo desktop do Word e queira criar um Office Script equivalente no Word para a web. Use como exemplo uma macro VBA simples que altera a fonte do primeiro parágrafo para negrito.

1. Abra o Word para a web e inicie um novo script
   No seu navegador, abra o documento no Word para a web. Clique em Automate na faixa de opções, depois em Script e em New Script. O painel Code Editor é aberto com um modelo de script padrão.
2. Remova o código padrão e escreva o wrapper assíncrono
   Selecione todo o código no editor e substitua por:

   function main(workbook: WordScript.Word) {
     // Seu código será inserido aqui
   }

   A função main é o ponto de entrada. Ela recebe o objeto WordScript.Word, que dá acesso ao documento.

3. Adicione o contexto Word.run
   Dentro de main, adicione:

   Word.run(async (context) => {
     // Operações aqui
     await context.sync();
   });

   O método Word.run cria um contexto de requisição. Toda operação de leitura ou escrita deve estar dentro deste callback. O await context.sync() envia todas as alterações enfileiradas para o documento.

4. Traduza a lógica VBA para a API do Office Scripts
   Para uma macro VBA que define o primeiro parágrafo como negrito:
   • VBA: ActiveDocument.Paragraphs(1).Range.Font.Bold = True
   • Office Scripts: context.document.body.paragraphs[0].font.bold = true;

   Coloque esta linha antes da chamada context.sync(). Observe que os arrays são indexados a partir de zero em TypeScript, então o primeiro parágrafo é paragraphs[0].

5. Execute o script para testar
   Clique no botão Run na barra de ferramentas do Code Editor. O script é executado e o primeiro parágrafo fica em negrito. Se aparecerem erros, verifique a saída do console abaixo do editor.
6. Salve o script com um nome significativo
   Clique no nome do script no topo do Code Editor (o padrão é “Untitled Script”), digite um novo nome e pressione Enter. O script é salvo no seu OneDrive e aparece na lista Automate > Script deste documento.

Problemas comuns ao migrar VBA para Office Scripts

Erro “Cannot find name ‘ActiveDocument'”

Os Office Scripts não usam o objeto ActiveDocument. Sempre acesse o documento através da propriedade context.document. O objeto context é a única maneira de interagir com o documento.

Erro “Property ‘Select’ does not exist”

Os Office Scripts não possuem um método Select. Você não pode selecionar texto ou intervalos programaticamente. Em vez disso, manipule o conteúdo diretamente. Por exemplo, para substituir texto, use range.insertText() ou range.insertHtml().

O script expira ao processar um documento grande

Os Office Scripts têm um limite de execução de 30 segundos. Se sua macro VBA percorre centenas de parágrafos, o script pode expirar. Otimize agrupando alterações em uma única chamada context.sync() e removendo chamadas context.sync() desnecessárias dentro de loops.

Office Scripts vs VBA: Principais diferenças para automação do Word

Item	VBA no Word Desktop	Office Scripts no Word para a Web
Ambiente de execução	Aplicativo desktop Windows/macOS	Runtime em nuvem baseado em navegador
Linguagem	Visual Basic for Applications	TypeScript (superconjunto de JavaScript)
Acesso ao modelo de objeto	Síncrono, direto	Assíncrono via context.sync()
Acionamento	Atalho de teclado, botão, evento	Execução manual, Power Automate, agendado
Seleção de documento	ActiveDocument ou ThisDocument	context.document
Tratamento de erros	On Error Resume Next / GoTo	Blocos try/catch
Tempo máximo de execução	Sem limite definido	30 segundos

Agora você pode identificar quais macros VBA são candidatas à migração para a nuvem e reescrevê-las como Office Scripts. Comece com uma macro simples que modifica formatação ou insere texto. Depois que o script funcionar no Word para a web, conecte-o a um fluxo do Power Automate para executar automaticamente quando um arquivo for adicionado a uma biblioteca do SharePoint. Para cenários avançados, explore a referência da API do Office Scripts para Word e descubra métodos adicionais como insertTable() e insertParagraph().