Como Usar Compilação Condicional em VBA do Word para Várias Versões do Office

Ao escrever macros VBA no Word, o código pode se comportar de forma diferente dependendo da versão do Office (2013, 2016, 2019, Microsoft 365). Recursos como a nova API de Comentários ou o Inspetor de Documentos mudaram entre versões. Sem detecção de versão, sua macro pode travar ou produzir resultados incorretos em versões não suportadas. A compilação condicional permite escrever uma macro que executa o bloco de código correto para cada versão do Office automaticamente.

Este artigo explica como a compilação condicional funciona no VBA do Word, como configurar constantes específicas de versão e como escrever macros que permanecem compatíveis com Office 2013 até Microsoft 365. Você aprenderá a sintaxe correta para blocos #If…Then…#Else e como testar seu código sem erros.

Como a Compilação Condicional Funciona no VBA do Word

A compilação condicional usa diretivas de compilador que o editor VBA avalia antes de executar o código. As diretivas são #If, #ElseIf, #Else e #End If. Diferente das instruções If...Then em tempo de execução, a compilação condicional exclui fisicamente os blocos de código inativos do binário compilado. Isso significa que a macro executa mais rápido e não falhará em versões não suportadas.

O editor VBA fornece duas constantes internas: VBA7 e Win64. VBA7 é True quando o aplicativo host usa a versão 7 do VBA, que começou com o Office 2010 64 bits. Win64 é True apenas quando o sistema operacional é Windows 64 bits. Você também pode definir suas próprias constantes usando #Const no topo de um módulo ou nas propriedades do projeto em Argumentos de Compilação Condicional.

Pré-requisitos para Usar Compilação Condicional

Você precisa de acesso ao editor VBA (Alt+F11) e de um documento ou modelo do Word que contenha macros. As diretivas condicionais funcionam em módulos padrão, módulos de classe e módulos de código de formulário. Nenhum complemento ou permissão especial é necessário. No entanto, você deve testar a macro compilada em cada versão de destino do Office para confirmar que o bloco de código correto é executado.

Passos para Configurar Compilação Condicional no VBA do Word

Siga estes passos para adicionar compilação condicional a uma macro existente ou para escrever uma nova macro segura para versões.

1. Abra o editor VBA e localize sua macro
   Pressione Alt+F11 no Word para abrir o editor VBA. No Project Explorer, clique duas vezes no módulo que contém sua macro. Se você ainda não tiver um módulo, clique com o botão direito no projeto, escolha Inserir > Módulo.
2. Defina uma constante de compilação condicional para a versão do Office
   No topo do módulo, adicione uma linha #Const. Por exemplo: #Const AppVersion = 16 para Office 2016, 2019 ou Microsoft 365. Use 15 para Office 2013. Esta constante será usada nos blocos #If.
3. Coloque o código específico da versão dentro de #If…#End If
   Escreva o código que funciona no Office 2016 ou posterior dentro de #If AppVersion = 16 Then. Escreva o código alternativo para Office 2013 dentro de #Else. Feche com #End If. Exemplo:

   #If AppVersion = 16 Then
       ' Usar o novo método Comments.Add2
       ActiveDocument.Comments.Add2 Range:=Selection.Range, Text:="Revisão"
   #Else
       ' Usar o método antigo Comments.Add
       ActiveDocument.Comments.Add Range:=Selection.Range, Text:="Revisão"
   #End If

4. Adicione detecção de 64 bits para instruções Declare de API
   Se sua macro usa funções da API do Windows, coloque a instrução Declare dentro de #If VBA7 Then. Para Office 64 bits, use a palavra-chave PtrSafe. Para 32 bits, omita-a. Exemplo:

   #If VBA7 Then
       Private Declare PtrSafe Function GetTickCount Lib "kernel32" () As Long
   #Else
       Private Declare Function GetTickCount Lib "kernel32" () As Long
   #End If

5. Teste a macro em cada versão de destino do Office
   Compile a macro (Depurar > Compilar Projeto VBA) em uma versão. Em seguida, copie o documento ou modelo para um computador executando uma versão diferente do Office. Execute a macro e verifique se o bloco de código correto é executado. Se você definiu a constante manualmente, altere seu valor e recompile antes de testar a outra versão.

Usando Argumentos de Compilação Condicional no Nível do Projeto

Em vez de #Const no topo de um módulo, você pode definir a constante globalmente para todo o projeto VBA. No editor VBA, clique em Ferramentas > Propriedades do Projeto. Na guia Geral, digite a constante no campo Argumentos de Compilação Condicional. Por exemplo: AppVersion = 16. Separe várias constantes com dois pontos: AppVersion = 16: DebugMode = 1. Este método mantém a constante fora do seu código e facilita a alteração para teste.

Erros Comuns ao Usar Compilação Condicional

“Erro de Compilação: Else sem If”

Este erro ocorre quando #Else ou #End If está escrito incorretamente ou ausente. Verifique se cada #If tem um #End If correspondente. As diretivas devem estar em linhas separadas e começar com o símbolo de hash no início da linha.

“Tipo Definido pelo Usuário Não Definido” em uma Versão Diferente

Se você usar um tipo personalizado que existe apenas em versões mais recentes do Office, coloque todo o bloco Type...End Type dentro de um bloco de compilação condicional. Caso contrário, o compilador sempre tentará compilá-lo e falhará em versões mais antigas.

Constante Condicional Não Avaliada em Tempo de Design

Quando você usa #Const dentro de um módulo, o valor da constante é avaliado apenas quando esse módulo é compilado. Se você alterar a constante em outro módulo, o primeiro módulo ainda usará o valor antigo. Para evitar confusão, defina todas as constantes de versão em um módulo padrão ou use argumentos de nível de projeto.

Esquecer de Recompilar Após Alterar a Constante

Alterar o valor de #Const não recompila automaticamente o projeto. Você deve executar Depurar > Compilar Projeto VBA para aplicar a alteração. Se você não recompilar, o código compilado antigo será executado e os blocos condicionais não serão atualizados.

Compilação Condicional vs Detecção de Versão em Tempo de Execução

Item	Compilação Condicional (#If)	Detecção em Tempo de Execução (If…Then)
Quando o código é avaliado	Em tempo de compilação	Em tempo de execução
Código inativo no binário compilado	Excluído completamente	Ainda presente, mas não executado
Prevenção de erros em versão não suportada	Previne erros de compilação	Não pode prevenir erros de compilação de Declare de API ou objetos ausentes
Impacto no desempenho	Nenhum	Pequena sobrecarga da verificação de versão
Melhor caso de uso	Instruções Declare de API, diferenças no modelo de objeto que causam erros de compilação	Diferenças menores de comportamento que não afetam a compilação

A compilação condicional é a única maneira segura de lidar com diferenças que causam erros de compilação, como métodos ausentes ou declarações de API de 32 bits versus 64 bits. A detecção em tempo de execução funciona para diferenças apenas em tempo de execução, como valores de propriedade padrão ou pequenas alterações na interface do usuário.

Agora você pode escrever macros VBA do Word que funcionam no Office 2013, 2016, 2019 e Microsoft 365 sem arquivos de código separados. Use #Const ou Propriedades do Projeto para definir seu sinalizador de versão, coloque o código específico da versão em blocos #If...#End If e sempre recompile após alterar a constante. Para macros com muitas APIs, adicione #If VBA7 Then com PtrSafe para suportar Office 64 bits. Essa abordagem mantém seu código limpo, reduz o trabalho de manutenção e evita travamentos em versões não suportadas.