Criar funções personalizadas no ExcelCreate custom functions in Excel

Funções personalizadas permitem que desenvolvedores adicionem novas funções do Excel definindo essas funções em JavaScript como parte de um suplemento.Custom functions enable developers to add new functions to Excel by defining those functions in JavaScript as part of an add-in. Os usuários do Excel podem acessar funções personalizadas da mesma forma que fariam com qualquer função nativa no Excel, como SUM().Users within Excel can access custom functions just as they would any native function in Excel, such as SUM().

Importante

Observe que as funções personalizadas do Excel estão disponíveis nas seguintes plataformas.Note that Excel custom functions are available on the following platforms.

  • Office no WindowsOffice on Windows
  • Office no MacOffice on Mac
  • Office na WebOffice on the web

As funções personalizadas do Excel não são suportadas no iPad ou nas versões de compras de um único momento do Office 2019 ou anterior.Excel custom functions are currently not supported on iPad or in one-time purchase versions of Office 2019 or earlier.

A imagem animada a seguir mostra a sua pasta de trabalho solicitando uma função que você criou com o JavaScript ou o Typescript.The following animated image shows your workbook calling a function you've created with JavaScript or Typescript. Neste exemplo, a função personalizada =MYFUNCTION.SPHEREVOLUME calcula o volume de uma esfera.In this example, the custom function =MYFUNCTION.SPHEREVOLUME calculates the volume of a sphere.

animated image showing an end user inserting the MYFUNCTION.SPHEREVOLUME custom function into a cell of an Excel worksheet

O código a seguir define a função personalizada =MYFUNCTION.SPHEREVOLUME.The following code defines the custom function =MYFUNCTION.SPHEREVOLUME.

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

Observação

A seção Problemas conhecidos neste artigo especifica as atuais limitações de funções personalizadas.The Known issues section later in this article specifies current limitations of custom functions.

Como uma função personalizada é definida em códigoHow a custom function is defined in code

Se você usar o Gerador Yo 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.If you use the Yo Office generator to create an Excel custom functions add-in project, it creates files which control your functions and task pane. Vamos nos concentrar em arquivos que são importantes para funções personalizadas:We'll concentrate on the files that are important to custom functions:

FileFile Formato de arquivoFile format DescriçãoDescription
./src/functions/functions.js./src/functions/functions.js
ouor
./src/functions/functions.ts./src/functions/functions.ts
JavaScriptJavaScript
ouor
TypeScriptTypeScript
Contém o código que define funções personalizadas.Contains the code that defines custom functions.
./src/functions/functions.html./src/functions/functions.html HTMLHTML Fornece uma referência<script>ao arquivo JavaScript que define funções personalizadas.Provides a <script> reference to the JavaScript file that defines custom functions.
./manifest.xml./manifest.xml XMLXML Especifica o local de vários arquivos que a sua função personalizada usa, como as funções personalizadas JavaScript, JSON e arquivos HTML.Specifies the location of multiple files that your custom function use, such as the custom functions JavaScript, JSON, and HTML files. 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.It also lists the locations of task pane files, command files, and specifies which runtime your custom functions should use.

Arquivo de scriptScript file

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.The script file ( ./src/functions/functions.js or ./src/functions/functions.ts ) contains the code that defines custom functions and comments which define the function.

O código a seguir define a função personalizada add.The following code defines the custom function 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.The code comments are used to generate a JSON metadata file that describes the custom function to Excel. O necessário @customfunction comentário é declarado primeiro, para indicar que se trata de uma função personalizada.The required @customfunction comment is declared first, to indicate that this is a custom function. Em seguida, dois parâmetros são declarados, first e second, seguidos por suas propriedades de description.Next, two parameters are declared, first and second, followed by their description properties. Por fim, uma returns descrição é fornecida.Finally, a returns description is given. 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.For more information about what comments are required for your custom function, see Autogenerate JSON metadata for custom functions.

/**
 * 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 manifestoManifest file

O arquivo de manifesto XML para um suplemento que define funções personalizadas ( ./manifest.xml no projeto que o gerador de Yo Office cria) faz várias coisas:The XML manifest file for an add-in that defines custom functions ( ./manifest.xml in the project that the Yo Office generator creates) does several things:

  • Define o espaço de nomes das suas funções personalizadas.Defines the namespace for your custom functions. Um namespace se direciona para suas funções personalizadas para ajudar os clientes a identificar suas funções como parte do seu suplemento.A namespace prepends itself to your custom functions to help customers identify your functions as part of your add-in.
  • Usa os elementos <ExtensionPoint> e <Resources> que são exclusivos de um manifesto de funções personalizadas.Uses <ExtensionPoint> and <Resources> elements that are unique to a custom functions manifest. Esses elementos contêm informações sobre os locais dos arquivos JavaScript, JSON e HTML.These elements contain the information about the locations of the JavaScript, JSON, and HTML files.
  • Especifica o tempo de execução a ser usado para a sua função personalizada.Specifies which runtime to use for your custom function. 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.We recommend always using a shared runtime unless you have a specific need for another runtime, because a shared runtime allows for the sharing of data between functions and the task pane. Observe que usar um tempo de execução compartilhado significa que seu suplemento usará o Internet Explorer 11, não o Microsoft Edge.Note that using a shared runtime means your add-in will use Internet Explorer 11, not Microsoft Edge.

Se você estiver usando o gerador do Yo Office para criar arquivos, recomendamos ajustar o manifesto para usar o tempo de execução compartilhado, uma vez que esse não é o padrão para esses arquivos.If you are using the Yo Office generator to create files, we recommend adjusting your manifest to use a shared runtime, as this is not the default for these files. Para alterar o manifesto, siga as instruções no Configurar seu suplemento do Excel para usar um de tempo de execução JavaScript compartilhado.To change your manifest, follow the instructions in Configure your Excel add-in to use a shared JavaScript runtime.

Para ver um manifesto funcional completo de um suplemento de amostra, consulte esse repositório do GitHub.To see a full working manifest from a sample add-in, see this Github repository.

Dica

Se você estiver testando seu suplemento em vários ambientes (por exemplo, em desenvolvimento, preparação, demonstração, etc.), recomendamos que você mantenha um arquivo de manifesto XML diferente para cada ambiente.If you'll be testing your add-in across multiple environments (for example, in development, staging, demo, etc.), we recommend that you maintain a different XML manifest file for each environment. Em cada arquivo de manifesto, você pode:In each manifest file, you can:

  • Especifique as URLs que correspondem ao ambiente.Specify the URLs that correspond to the environment.
  • Personalizar os valores de metadados como DisplayName e os rótulos dentro Resources para indicar o ambiente, para que os usuários finais possam identificar o ambiente correspondente do suplemento do suplementos foi feito.Customize metadata values like DisplayName and labels within Resources to indicate the environment, so that end users will be able to identify a sideloaded add-in's corresponding environment.
  • Personalizar as funções personalizadas namespace para indicar o ambiente, se seu suplemento define funções personalizadas.Customize the custom functions namespace to indicate the environment, if your add-in defines custom functions.

Seguindo este guia, você simplificará o processo de teste e evitará problemas que poderiam ocorrer quando um suplemento estiver simultaneamente suplementos foi feito para vários ambientes.By following this guidance, you'll streamline the testing process and avoid issues that would otherwise occur when an add-in is simultaneously sideloaded for multiple environments.

CoautoriaCoauthoring

O Excel na Web e o Windows conectado a uma assinatura do Microsoft 365 permitem que você se conecte ao Excel.Excel on the web and Windows connected to a Microsoft 365 subscription allow you to coauthor in Excel. Se a pasta de trabalho usa uma função personalizada, seu colega será solicitado a carregar o suplemento da função personalizada.If your workbook uses a custom function, your coauthoring colleague is prompted to load the custom function's add-in. Depois de carregarem o suplemento, a função personalizada compartilhará resultados por meio de coautoria.Once you both have loaded the add-in, the custom function shares results through coauthoring.

Para saber mais sobre coautoria, confira o tópico Sobre o recurso de coautoria no Excel.For more information on coauthoring, see About coauthoring in Excel.

Problemas conhecidosKnown issues

Veja os problemas conhecidos no nosso GitHub de funções do Excel personalizado repo.See known issues on our Excel Custom Functions GitHub repo.

Próximas etapasNext steps

Quer experimentar funções personalizadas?Want to try out custom functions? 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.Check out the simple custom functions quick start or the more in-depth custom functions tutorial if you haven't already.

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.Another easy way to try out custom functions is to use Script Lab, an add-in that allows you to experiment with custom functions right in Excel. Você pode experimentar criar a sua própria função personalizada ou usar os exemplos disponíveis.You can try out creating your own custom function or play with the provided samples.

Confira tambémSee also