Criar funções personalizadas no Excel

  • Artigo

Funções personalizadas permitem que desenvolvedores adicionem novas funções do Excel definindo essas funções em JavaScript como parte de um suplemento. Os usuários do Excel podem acessar funções personalizadas da mesma forma que fariam com qualquer função nativa no Excel, como SUM().

Observação

Função personalizada é um termo geral que é intercambiável com a função definida pelo usuário. Ambos os termos se aplicam a suplementos VBA, COM e Office.js. A documentação de Suplementos do Office usa o termo função personalizada ao se referir a funções personalizadas que usam APIs JavaScript do Office.

Importante

Observe que as funções personalizadas do Excel estão disponíveis nas plataformas a seguir.

  • Office no Windows
    • Assinatura do Microsoft 365
    • varejo perpétuo Office 2016 e posterior
  • Office no Mac
  • Office na Web

No momento, não há suporte para funções personalizadas do Excel no seguinte:

  • Office no iPad
  • versões perpétuas licenciadas por volume do Office 2019 ou anteriores

A imagem animada a seguir mostra sua pasta de trabalho chamando uma função que você criou com JavaScript ou TypeScript. Neste exemplo, a função personalizada =MYFUNCTION.SPHEREVOLUME calcula o volume de uma esfera.

Imagem animada mostrando um usuário final inserindo MYFUNCTION. Função personalizada SPHEREVOLUME em uma célula de uma planilha do Excel.

O código a seguir define a função personalizada =MYFUNCTION.SPHEREVOLUME.

/**
 * Returns the volume of a sphere.
 * @customfunction
 * @param {number} radius
 */
function sphereVolume(radius) {
  return Math.pow(radius, 3) * 4 * Math.PI / 3;
}

Como uma função personalizada é definida em código

Se você usar o Gerador do Yeoman para Suplementos do Office para criar um projeto de suplemento funções personalizadas do Excel, ele criará os arquivos que controlam as funções e o painel de tarefas. Vamos nos concentrar em arquivos que são importantes para funções personalizadas.

File Formato de arquivo Descrição
./src/functions/functions.js
ou
./src/functions/functions.ts		 JavaScript
ou
TypeScript		 Contém o código que define funções personalizadas.
./src/functions/functions.html HTML Fornece uma referência<script>ao arquivo JavaScript que define funções personalizadas.
./manifest.xml XML Especifica o local de vários arquivos que a sua função personalizada usa, como as funções personalizadas JavaScript, JSON e arquivos HTML. Ele também lista os locais de arquivos do painel de tarefas, os arquivos de comando e especifica o tempo de execução que suas funções personalizadas devem usar.

Dica

O gerador Yeoman para suplementos do Office oferece vários projetos de Funções Personalizadas do Excel . Recomendamos selecionar o tipo de projeto Excel Custom Functions usando um Runtime Compartilhado e o tipo de script JavaScript.

Arquivo de script

O arquivo de script (./src/functions/functions.js ou ./src/functions/functions.ts) contém o código que define funções e comentários que definem a função.

O código a seguir define a função personalizada add. Os comentários do código são usados para gerar um arquivo de metadados JSON que descreve a função personalizada ao Excel. O necessário @customfunction comentário é declarado primeiro, para indicar que se trata de uma função personalizada. Em seguida, dois parâmetros são declarados, first e second, seguidos por suas propriedades de description. Por fim, uma returns descrição é fornecida. Para obter mais informações sobre quais comentários são necessários para sua função personalizada, confira Gerar automaticamente os metadados JSON para funções personalizadas.

/**
 * Adds two numbers.
 * @customfunction 
 * @param first First number.
 * @param second Second number.
 * @returns The sum of the two numbers.
 */

function add(first, second){
  return first + second;
}

Arquivo de manifesto

O arquivo de manifesto XML para um suplemento que define funções personalizadas (./manifest.xml no projeto que o Gerador do Yeoman para Suplementos do Office cria) faz várias coisas.

  • Define o espaço de nomes das suas funções personalizadas. Um namespace se direciona para suas funções personalizadas para ajudar os clientes a identificar suas funções como parte do seu suplemento.
  • Usa elementos ExtensionPoint> e Resources exclusivos< para um manifesto de funções personalizadas.>< Esses elementos contêm informações sobre os locais dos arquivos JavaScript, JSON e HTML.
  • Especifica o tempo de execução a ser usado para a sua função personalizada. Recomendamos sempre usar um tempo de execução compartilhado, a menos que você tenha uma necessidade específica para outro tempo de execução, porque um tempo de execução compartilhado permite o compartilhamento de dados entre funções e o painel de tarefas.

Para ver um manifesto de trabalho completo de um suplemento de exemplo, confira o manifesto em um dos nossos repositórios Github de exemplos de Suplementos do Office.

Dica

Se você estiver testando seu suplemento em vários ambientes (por exemplo, em desenvolvimento, preparo, demonstração, etc.), recomendamos que você mantenha um arquivo de manifesto XML diferente para cada ambiente. Em cada arquivo de manifesto, você pode:

  • Especificar as URLs que correspondem ao ambiente.
  • Personalize valores de metadados como DisplayName e rótulos em Resources para indicar o ambiente, assim os usuários finais poderão identificar o ambiente correspondente de um suplemento por sideloaded.
  • Personalize o namespace de funções personalizadas para indicar o ambiente, se o suplemento definir funções personalizadas.

Seguindo essas diretrizes, você simplificará o processo de teste e evitará problemas que, de outra forma, ocorreriam quando um suplemento fosse carregado simultaneamente em vários ambientes.

Coautoria

O Excel na Web e no Windows conectado a uma assinatura do Microsoft 365 permite que o usuário final seja coautor no Excel. Se a pasta de trabalho de um usuário final usar uma função personalizada, o colega de coautoria desse usuário final será solicitado a carregar o suplemento de funções personalizadas correspondente. Depois que ambos carregarem o suplemento, a função personalizada compartilhará resultados por meio de coautoria.

Para saber mais sobre coautoria, confira o tópico Sobre o recurso de coautoria no Excel.

Próximas etapas

Quer experimentar funções personalizadas? Confira o simples início rápido das funções personalizadas ou o mais detalhado tutorial de funções personalizadas, caso ainda não tenha.

Outra maneira fácil de experimentar as funções personalizadas é usar o Script Lab, que é um suplemento que permite com que você experimente as funções personalizadas diretamente no Excel. Você pode experimentar criar a sua própria função personalizada ou usar os exemplos disponíveis.

Confira também