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(). Este artigo descreve como criar as funções personalizadas no Excel.This article describes how to create custom functions in Excel.

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 Windows (versão 1904 ou posterior, conectado ao Office 365 assinatura)Office on Windows (version 1904 or later, connected to Office 365 subscription)
  • Office no Mac (versão 16,24 ou posterior, conectado ao Office 365 assinatura)Office on Mac (version 16.24 or later, connected to Office 365 subscription)
  • 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 funções personalizadas em um projeto do Excel, você encontrará que cria os arquivos que controlam as funções, o painel de tarefas e o suplemento geral.If you use the Yo Office generator to create an Excel custom functions add-in project, you'll find that it creates files which control your functions, your task pane, and your add-in overall. 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 namespace para todas as funções personalizadas no suplemento e o local dos arquivos JavaScript e HTML listados anteriormente nesta tabela.Specifies the namespace for all custom functions within the add-in and the location of the JavaScript and HTML files that are listed previously in this table. Também lista os locais de outros arquivos, que o suplemento pode fazer uso, como os arquivos do painel de tarefas e arquivos de comando.It also lists the locations of other files your add-in might make use of, such as the task pane files and command files.

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, comments which define the function, and associates the names of the custom functions to objects in the JSON metadata file.

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. Além disso, observe que dois parâmetros foram declarados, first e second, que é seguido por suas description propriedades.Additionally, you'll notice two parameters are declared, first and second, which are 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 Criar metadados JSON para funções personalizadas.For more information about what comments are required for your custom function, see Create 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;
}

Note que o arquivo functions.html, que governa o carregamento do tempo de execução das funções personalizadas, deve vincular-se à CDN atual para as funções personalizadas.Note that the functions.html file, which governs the loading of the custom functions runtime, must link to the current CDN for custom functions. Projetos preparados com a versão atual do gerador Yo Office referenciam a CDN correta.Projects prepared with the current version of the Yo Office generator reference the correct CDN. Se você estiver readaptando um projeto anterior de função personalizada de março de 2019 ou anteriormente, você precisará copiar no código abaixo para a página functions.html.If you are retrofitting a previous custom function project from March 2019 or earlier, you need to copy in the code below to the functions.html page.

<script src="https://appsforoffice.microsoft.com/lib/beta/hosted/custom-functions-runtime.js" type="text/javascript"></script>

Arquivo de manifestoManifest file

O arquivo de manifesto XML para um suplemento que define funções personalizadas (./manifest.xml no projeto gerador que Yo Office cria) especifica o namespace para todas as funções personalizadas no suplemento e o local dos arquivos HTML, JavaScript e JSON.The XML manifest file for an add-in that defines custom functions (./manifest.xml in the project that the Yo Office generator creates) specifies the namespace for all custom functions within the add-in and the location of the JavaScript, JSON, and HTML files.

A marcação XML a seguir mostra um exemplo dos elementos <ExtensionPoint> e <Resources> que você deve incluir no manifesto de um suplemento para habilitar funções personalizadas.The following basic XML markup shows an example of the <ExtensionPoint> and <Resources> elements that you must include in an add-in's manifest to enable custom functions. Se estiver usando o gerador Yo Office, seus arquivos de funções personalizadas gerados conterão um arquivo de manifesto mais complexo, que você pode comparar neste repositório do Github.If using the Yo Office generator, your generated custom function files will contain a more complex manifest file, which you can compare on this Github repository.

Observação

As URLs especificadas no arquivo de manifesto para as funções personalizadas JavaScript e JSON e arquivos HTML devem estar publicamente acessíveis e ter o mesmo subdomínio.The URLs specified in the manifest file for the custom functions JavaScript, JSON, and HTML files must be publicly accessible and have the same subdomain.

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bt="http://schemas.microsoft.com/office/officeappbasictypes/1.0" xmlns:ov="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="TaskPaneApp">
  <Id>6f4e46e8-07a8-4644-b126-547d5b539ece</Id>
  <Version>1.0.0.0</Version>
  <ProviderName>Contoso</ProviderName>
  <DefaultLocale>en-US</DefaultLocale>
  <DisplayName DefaultValue="helloworld"/>
  <Description DefaultValue="Samples to test custom functions"/>
  <Hosts>
    <Host Name="Workbook"/>
  </Hosts>
  <DefaultSettings>
    <SourceLocation DefaultValue="https://localhost:8081/index.html"/>
  </DefaultSettings>
  <Permissions>ReadWriteDocument</Permissions>
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/taskpaneappversionoverrides" xsi:type="VersionOverridesV1_0">
    <Hosts>
      <Host xsi:type="Workbook">
        <AllFormFactors>
          <ExtensionPoint xsi:type="CustomFunctions">
            <Script>
              <SourceLocation resid="JS-URL"/>
            </Script>
            <Page>
              <SourceLocation resid="HTML-URL"/>
            </Page>
            <Metadata>
              <SourceLocation resid="JSON-URL"/>
            </Metadata>
            <Namespace resid="namespace"/>
          </ExtensionPoint>
        </AllFormFactors>
      </Host>
    </Hosts>
    <Resources>
      <bt:Urls>
        <bt:Url id="JSON-URL" DefaultValue="https://subdomain.contoso.com/config/customfunctions.json"/>
        <bt:Url id="JS-URL" DefaultValue="https://subdomain.contoso.com/dist/win32/ship/index.win32.bundle"/>
        <bt:Url id="HTML-URL" DefaultValue="https://subdomain.contoso.com/index.html"/>
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="namespace" DefaultValue="CONTOSO"/>
      </bt:ShortStrings>
    </Resources>
  </VersionOverrides>
</OfficeApp>

Observação

Funções do Excel são anexadas ao namespace especificado no seu arquivo de manifesto XML.Functions in Excel are prepended by the namespace specified in your XML manifest file. O namespace da função vem antes do nome da função e são separados por um ponto.A function's namespace comes before the function name and they are separated by a period. Por exemplo, para acionar a funçãoADD42 na célula de uma planilha do Excel, você digitaria =CONTOSO.ADD42, porque CONTOSO é o namespace e ADD42 é o nome da função especificada no arquivo JSON.For example, to call the function ADD42 in the cell of an Excel worksheet, you would type =CONTOSO.ADD42, because CONTOSO is the namespace and ADD42 is the name of the function specified in the JSON file. O namespace deve ser usado como identificador para o as sua empresa ou suplemento.The namespace is intended to be used as an identifier for your company or the add-in. Um namespace pode conter apenas caracteres alfanuméricos e períodos.A namespace can only contain alphanumeric characters and periods.

CoautoriaCoauthoring

O Excel Online e no Windows conectado a uma assinatura do Office 365 permitem editar documentos em coautoria, e esse recurso funciona com funções personalizadas.Excel Online and Excel on Windows with an Office 365 subscription allow you to coauthor documents and this feature works with custom functions. 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 colleague will be 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 will share 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.

Pronto para ler mais sobre os recursos de funções personalizadas?Ready to read more about the capabilities custom functions? Saiba mais sobre a visão geral da arquitetura de funções personalizadas.Learn about an overview of the custom functions architecture.

Confira tambémSee also