Você tem uma macro VBA do Word que automatiza uma tarefa repetitiva, como formatar documentos ou inserir texto padrão. Distribuir essa macro para outros usuários é difícil porque cada pessoa precisa importá-la manualmente para o modelo Normal.dotm ou para um documento. Os Suplementos do Office oferecem uma maneira moderna e segura de compartilhar funcionalidades entre Word, Excel e PowerPoint sem exigir que os usuários confiem em macros VBA. Este artigo explica como converter sua macro VBA existente em um Suplemento do Office usando um painel de tarefas e um arquivo de script.

Principais Conclusões: Convertendo uma Macro VBA em um Suplemento de Painel de Tarefas

Suplementos do Office usam tecnologias web (HTML, JavaScript, CSS): Substitua o código VBA por JavaScript e hospede os arquivos em um servidor web ou pasta local.
O manifesto XML define a identidade e os recursos do suplemento: O manifesto informa ao Word onde encontrar seus arquivos e como exibir o painel de tarefas.
O sideloading é o método de teste mais simples: Use o menu Inserir > Suplementos > Meus Suplementos do Word para carregar um suplemento não assinado durante o desenvolvimento.

O que é um Suplemento do Office e como ele difere do VBA

Um Suplemento do Office é um aplicativo web executado dentro do Word, Excel ou PowerPoint. Ele usa HTML, JavaScript e CSS em vez de VBA. O suplemento se comunica com o aplicativo Office por meio da API JavaScript do Office, que fornece acesso ao documento, seleção e configurações.

As macros VBA são executadas diretamente no processo do Word e têm acesso total ao modelo de objeto e aos recursos do sistema. Os Suplementos do Office são executados em um controle de navegador em área restrita (sandbox). Essa área restrita impede que o suplemento acesse o sistema de arquivos local ou execute executáveis externos. O benefício é que os usuários não precisam reduzir suas configurações de segurança para habilitar macros. O suplemento pode ser distribuído por meio do AppSource, de um compartilhamento de rede ou de uma URL.

Antes de começar, você precisa do seguinte:

Word 2019, Word 2021, Word para Microsoft 365 ou Word na web
Um editor de texto como Notepad ou Visual Studio Code
Conhecimento básico de JavaScript e HTML
Seu código de macro VBA como referência para a lógica que deseja replicar

Etapas para Converter uma Macro VBA em um Suplemento do Office

A conversão envolve três tarefas principais: criar o arquivo de manifesto XML, escrever os arquivos HTML e JavaScript e fazer o sideload do suplemento para testá-lo. O exemplo abaixo converte uma macro VBA simples que insere a data atual no documento.

Etapa 1: Criar o Arquivo de Manifesto XML

Crie uma nova pasta
Nomeie-a como DateAddin. Esta pasta conterá todos os arquivos do suplemento.

Crie um arquivo chamado manifest.xml
Abra um editor de texto e cole o seguinte XML. Substitua https://localhost:3000 pela URL onde você hospeda os arquivos ou use o caminho local durante o teste.

<?xml version="1.0" encoding="UTF-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="TaskPaneApp">
  <Id>c7a8b9d0-1234-5678-9abc-def012345678</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Seu Nome</ProviderName>
  <DefaultLocale>pt-BR</DefaultLocale>
  <DisplayName DefaultValue="Suplemento Inserir Data"/>
  <Description DefaultValue="Insere a data atual na posição do cursor."/>
  <Hosts>
    <Host Name="Document"/>
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:3000/index.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
</OfficeApp>

Gere um GUID único para o elemento Id
Use um gerador de GUID online ou execute [guid]::NewGuid() no PowerShell. Cada suplemento deve ter um ID único.

Etapa 2: Criar os Arquivos HTML e JavaScript

Crie index.html
Na mesma pasta, crie um arquivo chamado index.html. Adicione a seguinte estrutura HTML:

<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8">
  <meta http-equiv="X-UA-Compatible" content="IE=edge">
  <title>Suplemento Inserir Data</title>
  <script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
  <script src="app.js"></script>
</head>
<body>
  <h1>Inserir Data</h1>
  <button id="insertDate">Inserir Data Atual</button>
</body>
</html>

Crie app.js
Crie um arquivo chamado app.js na mesma pasta. Adicione o seguinte JavaScript. Este código replica uma macro VBA que digita a data atual no documento.

Office.onReady(function(info) {
  if (info.host === Office.HostType.Word) {
    document.getElementById("insertDate").onclick = function() {
      Word.run(function(context) {
        var today = new Date();
        var dateString = today.toLocaleDateString();
        var selection = context.document.getSelection();
        selection.insertText(dateString, Word.InsertLocation.replace);
        return context.sync();
      }).catch(function(error) {
        console.log(error);
      });
    };
  }
});

Consulte a referência da API JavaScript do Office para suas ações de macro
Se sua macro VBA usa métodos como Selection.TypeText ou Selection.InsertAfter, pesquise na documentação da API JavaScript do Office o método equivalente. O método insertText no exemplo acima substitui o texto selecionado.

Etapa 3: Hospedar os Arquivos e Fazer o Sideload do Suplemento

Hospede os arquivos em um servidor web local ou em um compartilhamento de rede
Para teste, use um servidor HTTP simples. Com o Node.js instalado, execute npx http-server -p 3000 na pasta DateAddin. O servidor deve usar HTTPS para Suplementos do Office. Use um certificado autoassinado ou execute o comando com a flag -S e um arquivo de certificado.
Abra o Word e vá em Inserir > Suplementos > Meus Suplementos
Clique em Carregar Meu Suplemento na parte inferior da caixa de diálogo.
Navegue até seu arquivo manifest.xml
Selecione o arquivo e clique em Carregar. O suplemento aparece no painel de tarefas.
Teste o suplemento
Posicione o cursor em um documento e clique no botão Inserir Data Atual. A data atual deve aparecer.

Problemas Comuns de Conversão e Como Corrigi-los

O Painel de Tarefas Mostra um Erro ou Página em Branco

Isso geralmente significa que a URL SourceLocation no manifesto está incorreta ou o servidor web não está em execução. Verifique se a URL corresponde exatamente ao endereço do servidor, incluindo o número da porta. Se estiver usando localhost, certifique-se de que o servidor esteja ativo e o certificado seja confiável. Abra as ferramentas do desenvolvedor do navegador no painel de tarefas clicando com o botão direito e selecionando Inspecionar para ver os erros do console.

O Método da API JavaScript Não Funciona como Esperado

A API JavaScript do Office não cobre todos os métodos VBA. Por exemplo, não há equivalente direto para Dialogs ou FileDialog. Você deve usar controles de formulário HTML para entrada do usuário. Consulte a referência da API JavaScript do Microsoft Office para métodos disponíveis. Se um método estiver faltando, você pode combinar várias chamadas de API ou usar propriedades de Office.context.document.

O Suplemento Funciona Apenas no Word Online, mas Não no Word Desktop

O Word Desktop exige que o suplemento seja servido via HTTPS com um certificado válido. Certificados autoassinados funcionam para teste, mas podem exigir que você adicione o certificado ao repositório de Autoridades de Certificação Raiz Confiáveis na máquina local. Para produção, use um certificado de uma autoridade de certificação confiável.

Macro VBA vs Suplemento do Office: Principais Diferenças para Desenvolvedores

Item	Macro VBA	Suplemento do Office
Linguagem de programação	VBA (Visual Basic for Applications)	JavaScript com HTML e CSS
Método de distribuição	Incorporado no documento ou modelo	Manifesto XML apontando para arquivos hospedados
Modelo de segurança	Depende das configurações de segurança de macro	Área restrita (sandbox), sem acesso ao sistema de arquivos
Suporte multiplataforma	Windows e Mac (limitado)	Windows, Mac, web, iOS, Android
Instalação pelo usuário	Importação manual ou local confiável	Um clique em Inserir > Suplementos
Mecanismo de atualização	Substituir a macro manualmente	Atualizar arquivos no servidor; os usuários recebem a versão mais recente no próximo carregamento

Converter uma macro VBA em um Suplemento do Office oferece um método de distribuição moderno que funciona em várias plataformas sem avisos de segurança. Comece replicando a lógica principal em JavaScript usando a API JavaScript do Office. Após testar com sideload, você pode publicar o suplemento no catálogo da sua organização ou no AppSource. Para macros complexas, considere dividir a funcionalidade em várias funções e usar um painel de tarefas com botões ou menus suspensos para interação do usuário.

← Back to WiseChecker Home More in Word Solutions