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

A função personalizada é um termo geral que é intercambiável com a função definida pelo utilizador. Ambos os termos aplicam-se aos suplementos VBA, COM e Office.js. A documentação suplementos do Office utiliza o termo função personalizada quando se refere a funções personalizadas que utilizam APIs JavaScript do Office.

Importante

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

  • Office na Web
  • Office no Windows
    • Assinatura do Microsoft 365
    • revenda perpétua do Office 2016 e posterior
    • Office 2021 perpétuo licenciado em volume e posterior
  • Office no Mac

As funções personalizadas do Excel não são atualmente suportadas no seguinte:

  • Office no iPad
  • versões perpétuas licenciadas em volume do Office 2019 ou anterior no Windows

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 que selecione o tipo de projeto Funções Personalizadas do Excel com um Runtime Partilhado 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 ficheiro de manifesto apenas de suplemento para um suplemento que define funções personalizadas (./manifest.xml no projeto que o gerador 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.
  • Utiliza <elementos do ExtensionPoint> e <recursos> que são exclusivos de 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 estiver a testar o suplemento em vários ambientes (por exemplo, em desenvolvimento, teste, demonstração, etc.), recomendamos que mantenha um ficheiro de manifesto 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