Criar funções personalizadas no Excel

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 intercambiável com função definida pelo usuário. Ambos os termos se aplicam aos 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.

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 ou ./manifest.json XML ou JSON 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. O gerador Yeoman para Suplementos do Office cria um projeto com um manifesto XML.

Dica

O gerador Yeoman para Suplementos do Office oferece vários projetos de Funções Personalizadas do Excel . Recomendamos selecionar o tipo de projeto Funções Personalizadas do Excel 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;
}

Dica

No Excel na Web, as descrições de função personalizada e as descrições de parâmetro são exibidas embutidas. Isso fornece aos usuários informações adicionais ao escrever funções personalizadas. Saiba como configurar as descrições embutidas explorando qualquer um dos exemplos de funções personalizadas do Script Lab no Excel na Web. Consulte a captura de tela a seguir para ver um exemplo.

Uma função personalizada com descrições embutidas exibidas no Excel na Web.

Arquivo de manifesto

O arquivo de manifesto de um suplemento que define funções personalizadas, configura o namespace, especifica os locais dos arquivos e define o tempo de execução. Selecione a guia para o tipo de manifesto que você está usando.

O manifesto unificado de um suplemento que define funções personalizadas (./manifest.json no projeto) faz várias coisas.

  • Define o namespace para suas funções personalizadas usando o customFunctions.namespace objeto. Um namespace se direciona para suas funções personalizadas para ajudar os clientes a identificar suas funções como parte do seu suplemento.
  • Usa a customFunctions extensão para especificar metadados sobre funções personalizadas, incluindo o local do arquivo de metadados JSON por meio da metadataUrl propriedade.
  • Configura o tempo de execução para funções personalizadas usando a runtimes matriz com uma actions.type propriedade definida como "executeFunction".

Para ver um manifesto de trabalho completo de um suplemento de exemplo, consulte o manifesto em um de nossos repositórios GitHub de exemplos de Suplemento 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 diferente para cada ambiente. Em cada arquivo de manifesto, você pode:

  • Especificar as URLs que correspondem ao ambiente.

  • Personalize os valores de metadados para que os usuários finais possam identificar o ambiente correspondente de um suplemento com sideload. Por exemplo:

    • No manifesto unificado do Microsoft 365, personalize a "name" propriedade do suplemento e as "label" propriedades de vários controles de interface do usuário para indicar o ambiente.
    • No manifesto somente do suplemento, personalize o elemento e os DisplayName rótulos dentro do Resources elemento para indicar o ambiente.

  • 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.

Plataformas compatíveis

As funções personalizadas do Excel têm suporte na maioria dos aplicativos cliente do Office. No momento, não há suporte para funções personalizadas do Excel no Office no iPad ou em versões perpétuas licenciadas por volume do Office 2021 ou anteriores no Windows. Para obter mais informações, consulte Conjuntos de requisitos de funções personalizadas.

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

  • Last updated on