Função VBA – Chamada, Retorno de Valor e Parâmetros

Este tutorial lhe ensinará a criar e utilizar funções com e sem parâmetros no VBA.

O VBA possui uma grande quantidade de funções embutidas para você utilizar, mas você também pode escrever a sua próprias funções. Quando você escreve código em VBA, você pode escrevê-lo dentro de um Sub Procedure (Sub Procedimento), ou dentro de uma Function Procedure (Função Procedimento). Uma Function Procedure é capaz de retornar um valor para seu código.  Isso é extremamente útil se você quiser que o VBA execute uma tarefa e retorne um resultado. Funções do VBA podem também ser chamadas a partir do Excel, tal como as funções embutidas do Excel.

Criando uma Função sem Argumentos

Para criar uma função você precisa primeiro definir a função dando-lhe um nome. A função pode, então, ser definida indicando o tipo de dados que você deseja que a função retorne.

Você pode, por exemplo, criar uma função que retorne um valor estático a cada vez que é chamada – algo como uma constante.

Function ObterValor() As Integer
   ObterValor = 50
End Function

Se você executasse a função acima, ela sempre retornaria o valor de 50.

Você também pode criar funções que façam referência a objetos no VBA, porém, você precisa utilizar a palavra-chave Set para retornar o valor da função.

Function ObterIntervalo() as Range
  Set ObterIntervalo= Range("A1:G4")
End Function

Se você fosse utilizar a função acima no seu código VBA, a função iria sempre retornar o intervalo de células A1 a G4 em qualquer planilha em que você esteja trabalhando.

Chamando uma Função de dentro de um Sub Procedimento

Uma vez que você tenha criado a função, você pode chamá-la de qualquer outro lugar em seu código usando um Sub Procedimento.

Sempre o valor 50 será retornado.

Você também pode chamar a função ObterValor de dentro de um Sub Procedimento.

No exemplo acima, a função ObterIntervalo é chamada pelo Sub Procedimento para negritar as células do objeto Range retornado pela função.

Criando Funções

Argumento Único

Você também pode atribuir um parâmetro (ou mais) para sua função.  Estes parâmetros podem ser referenciados como Argumentos.

Function ConverterQuilogramaParaLibras (dblQuilograma as Double) as Double
   ConverterQuilogramaParaLibras = dblQuilograma*2.2
End Function

Podemos chamar a função acima a partir de um Sub Procedimento para descobrir quantas libras correspondem a uma quantidade específica de quilos.

Uma função pode ser chamada a partir de múltiplos procedimentos dentro do seu código VBA, se for necessário.  Isto é especialmente útil para evitar ter de reescrever o mesmo código várias vezes.  Isto também torna possível dividir longos procedimentos em pequenos blocos de funções.

No exemplo acima, temos 2 procedimentos – cada um está usando a Função ConverterQuilosParaLibras para calcular o valor em libras correspondente ao valor em quilos passado na chamada da função através do argumento dblQuilograma.

Múltiplos Argumentos

Você pode criar uma Função com múltiplos argumentos e passar os valores para a Função por meio de um Sub Procedimento.

Function CalculaDiferencaDias(Data1 As Date, Data2 As Date) As Double
   CalculaDiferencaDias= Data2 - Data1
End Function

Podemos então chamar a função para calcular o total de dias entre 2 datas.

Argumentos Opcionais

Você pode também passar Argumentos Opcionais para uma Função.  Em outras palavras, às vezes você pode precisar do argumento, e às vezes você pode não precisar – dependendo de em qual código você está utilizando a função.

Function CalculaDiferencaDias(Data1 As Date, Optional Data2 As Date) as Double
'Checa por uma possível segunda data, caso não tenha, faz com que Date2 seja igual a à data atual.
   If Data2 = 0 Then Data2 = Date
'Calcula a diferença
   CalculaDiferencaDias = Data2 - Data1 
End Function

Valor Padrão do Argumento

Você também pode definir um valor padrão para argumentos opcionais ao criar uma função, assim, se o usuário omitir o argumento, o valor que você definiu como padrão será utilizado.

Function CalculaDiferencaDias(Data1 As Date, Optional Data2 As Date="02/06/2020") As Double 
'Calcula a diferença 
   CalculaDiferencaDias= Data2 - Data1 
End Function

ByVal e ByRef

Ao passar valores para uma função, você pode usar as palavras-chave ByVal ou ByRef.  Se você omitir qualquer uma delas, o ByRef será utilizado por padrão.

ByVal significa que você está passando uma cópia da variável para a função, ao passo que ByRef significa que você está referenciando o valor original da variável.  Quando você passa uma cópia da variável (ByVal), o valor original da variável NÃO é alterado, porém, quando você referencia uma variável, o valor original é (ou pode ser)  alterado pela função.

Function ObterValor(ByRef intA As Integer) As Integer
   intA = intA * 4
   ObterValor = intA
End Function

Na função acima, o modificador ByRef poderia ter sido omitido e a função funcionaria do mesmo modo que abaixo.

Function ObterValor(intA As Integer) As Integer
   intA = intA * 4
   ObterValor = intA
End Function

Para chamar essa função, podemos executar um subprocedimento.

Sub TesteValores()
   Dim intValor As Integer
'Atribui o valor 10 à variável
   intValor = 10
'Executa a função ObterValor e mostra o valor na janela imediata
   Debug.Print ObterValor(intValor)
'Mostra o valor da variável intValor na janela imediata
   Debug.Print  intValor
End Sub

Note que a janela imediata mostra o valor 40 duas vezes.  Quando você passa a variável IntValor para a função  – o valor 10 é passado e multiplicado por 4.  Usando a palavra-chave ByRef (ou omitindo-a), irá ALTERAR o valor da variável IntValor.   Isto é melhor percebido quando você mostra o primeiro resultado da função na janela imediata (40), e então, mostra em seguida o valor da variável IntValor (também 40).

Se nós NÃO quisermos alterar o valor original da variável, precisamos utilizar a na função a palavra-chave ByVal.

Function ObterValor(ByVal intA As Integer) As Integer
   intA = intA * 4
   ObterValor= intA
End Function

Agora, se chamarmos a função a partir de um subprocedimento, o valor da variável IntValor irá permanecer inalterado, ou seja, permanecerá 10.

Exit Function

Você pode precisar criar uma função que verifique uma certa condição, e uma vez que essa condição é satisfeita (ou seja, quando é verdadeira), se você quiser retornar o valor da função sem precisar percorrer todo o código restante da mesma (uma vez que você já tem o valor que precisava), você pode precisar adicionar a instrução Exit Function na sua função.

Function EncontrarNumero(strTexto As String) As Integer
   Dim i As Integer
   'Loop através de cada letra da string
   For i = 1 To Len(strTexto)
   'Se a letra for numérica, retorna o valor para a função
      If IsNumeric(Mid(strTexto, i, 1)) Then
         EncontrarNumero = Mid(strTexto, i, 1)
        'Sai da função
         Exit Function
      End If
   Next
   EncontrarNumero = 0
End Function

A função acima irá fazer um loop através da string fornecida até encontrar um número, e então irá retornar o número encontrado.  Ela irá encontrar apenas o primeiro número na string, uma vez que logo em seguida irá SAIR (Exit Function) da função.

A função acima pode ser chamada por um subprocedimento como o exemplo abaixo.

Sub ChecagemDeNumeros()
   Dim intNumero as Integer
'Passa uma string para a função EncontrarNumero
   intNumero = EncontrarNumero("Andar Superior, quarto 8, Centro")
'Mostra o resultado na janela imediata
   Debug.Print intNumero 
End Sub

Usando uma Função de Dentro da Planilha Excel

Além de poder chamar uma função do seu código VBA utilizando um subprocedimento, você também pode chamar a função de dentro da sua Planilha Excel.  As funções que você criou no VBA, devem aparecer, por padrão, em sua lista de funções na categoria “Definido pelo Usuário”.

Clique em  fx para mostrar a caixa de diálogo Inserir Função.

Selecione Definido pelo Usuário na Lista de Categorias:

Selecione a função que desejar das UDF’s – User Defined Functions (Funções Definidas pelo Usuário) disponíveis.

Alternativamente, quando você começar a digitar o nome de sua função no Excel, a função deverá aparecer como uma das opções na lista de função no drop down.

Se você não quiser que sua função fique disponível para utilização dentro da planilha Excel, você precisa colocar a palavra-chave Private na frente da palavra Function ao criar uma função no seu código VBA.

Private Function CalculaDiferencaDias(Data1 As Date, Data2 As Date) As Double
    'Calcula a diferença
    CalculaDiferencaDias = Data2 - Data1
End Function

Após inserir a palavra Private na frente da palavra Function na definição de sua função no VBA, ela não irá mais aparecer como uma função disponível para ser utilizada no Planilha Excel.

Entretanto, é interessante notar que, mesmo que a função não apareça como uma opção disponível, ainda assim, é possível utililizá-la.

Se você declarou o segundo argumento como Optional, você pode omití-lo de dentro da Planilha Excel, tanto como de dentro do código VBA.

Você também pode utilizar na sua planilha Excel uma função que você tenha criado e que não possua argumentos: