Introdução ao desenvolvimento de funções personalizadas do Excel

Com as funções personalizadas, os desenvolvedores podem adicionar novas funções ao Excel definindo-as em JavaScript ou TypeScript 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().

Pré-requisitos

• Node.js (a versão LTS ativa mais recente). Visite o site doNode.js para baixar e instalar a versão correta para o seu sistema operacional.

• A versão mais recente do Yeoman e do Yeoman gerador de Suplementos do Office. Para instalar essas ferramentas globalmente, execute o seguinte comando por meio do prompt de comando.

  npm install -g yo generator-office
  

  Observação

  Mesmo se você já instalou o gerador Yeoman, recomendamos atualizar seu pacote para a versão mais recente do npm.

• Office conectado a uma assinatura Microsoft 365 (incluindo o Office na web).

  Observação

  Se você ainda não tem o Office, você pode se qualificar para uma assinatura de desenvolvedor do Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365. Para obter detalhes, consulte as Perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou adquirir um plano do Microsoft 365.

Crie seu primeiro projeto com funções personalizadas

Para começar, você usará o gerador Yeoman para criar projeto com funções personalizadas. Isso configurará seu projeto com a estrutura de pastas, arquivos de origem e dependências corretos para começar a codificar suas funções personalizadas.

1. Execute o comando a seguir para criar um projeto de suplemento usando o gerador Yeoman. Uma pasta que contém o projeto será adicionada ao diretório atual.

   yo office
   

   Observação

   Ao executar o comando yo office, você receberá informações sobre as políticas de coleta de dados de Yeoman e as ferramentas da CLI do suplemento do Office. Use as informações fornecidas para responder às solicitações como achar melhor.

   Quando solicitado, forneça as informações a seguir para criar seu projeto de suplemento.

   • Escolha um tipo de projeto:Excel Custom Functions using a Shared Runtime
   • Escolha um tipo de script:JavaScript
   • Como você deseja nomear seu suplemento?My custom functions add-in

   

   O gerador Yeoman criará os arquivos do projeto e instalará os componentes Node de suporte.

2. O gerador Yeoman fornece instruções em sua linha de comando sobre o projeto, mas você deve continuar seguindo as instruções deste artigo. Navegue até a pasta raiz do projeto.

   cd "My custom functions add-in"
   

3. Compile o projeto.

   npm run build
   

4. Inicie o servidor local da web, que é executado no Node.js. Você pode experimentar o suplemento de função personalizada no Excel. Você pode ser solicitado a abrir o painel de tarefas do suplemento, embora seja opcional. Ainda é possível executar as funções personalizadas sem abrir o painel de tarefas do suplemento.

npm run start -- web --document {url}

Experimente uma função personalizada predefinida

O projeto de funções personalizadas criado usando o gerador Yeoman contém algumas funções personalizadas predefinidas definidas no arquivo ./src/functions/functions.js. O arquivo ./manifest.xml na pasta raiz do projeto especifica que todas as funções personalizadas pertencem ao namespace CONTOSO.

Em sua pasta de trabalho do Excel experimente a função personalizada ADD preenchendo as seguintes etapas.

1. Selecione uma célula e digite =CONTOSO Observe que o menu de preenchimento automático mostra a lista de todas as funções no namespace CONTOSO.

2. Execute a CONTOSO.ADD função, usando números 10 e 200 como parâmetros de entrada, digitando o valor =CONTOSO.ADD(10,200) na célula e pressionando Enter.

O ADD função personalizada calcula a soma de dois números que você especificar como os parâmetros de entrada. A digitação =CONTOSO.ADD(10,200) deve produzir o resultado 210 na célula depois que você pressionar Enter.

Se o namespace CONTOSO não estiver disponível no menu de preenchimento automático, siga as etapas a seguir para registrar o suplemento no Excel.

Quando você quiser parar o servidor Web local e desinstalar o suplemento, siga as instruções aplicáveis:

• Para parar o servidor, execute o seguinte comando. Se você usou npm start, o comando a seguir também desinstala o suplemento.

  npm stop
  

• Se você carregou manualmente o suplemento, consulte Remover um suplemento com sideload.

Próximas etapas

Você criou com êxito uma função personalizada em um suplemento do Excel, parabéns! Em seguida, crie um suplemento mais complexo com o recurso de fluxo de dados. O link a seguir mostra as próximas etapas do tutorial do suplemento do Excel com funções personalizadas.

Solução de problemas

• Certifique-se de que seu ambiente esteja pronto para o desenvolvimento do Office seguindo as instruções em Configurar seu ambiente de desenvolvimento.

• A etapa automática npm install que o Yo Office executa pode falhar. Se você vir erros ao tentar executar npm start, navegue até a pasta do projeto recém-criada em um prompt de comando e execute npm installmanualmente . Para obter mais informações sobre o Yo Office, consulte Criar projetos de suplemento do Office usando o Gerador Yeoman.

• Você pode ver avisos gerados ao executar npm install o gerador Yeoman ou o projeto. Na maioria dos casos, você pode ignorar esses avisos com segurança. Às vezes, as dependências se tornam preteridas e suas substituições não têm suporte em outros pacotes dos quais o projeto depende. Se você quiser resolver esses avisos, use a npm-check-updates ferramenta.

  • No prompt de comando, enquanto estiver no diretório raiz do projeto, execute npm i -g npm-check-updates. Isso instala a ferramenta globalmente.
  • Execute ncu -u. Isso fornece um relatório de todos os pacotes e para quais versões eles serão atualizados.
  • Execute npm install para atualizar todos os pacotes.

  Para obter mais informações sobre avisos durante a execução npm install, consulte Avisos e dependências no mundo Node.js e npm.

• Se você não vir o botão do suplemento na faixa de opções (por exemplo, Mostrar Painel de Tarefas), selecione o botão Suplementos na guia da faixa de opções Página Inicial e escolha o suplemento de teste.

• Você poderá encontrar problemas se executar o início rápido várias vezes. Se o Office cache já tiver uma instância de uma função com o mesmo nome, o seu complemento obtém um erro quando ele é sideload. Você pode evitar isso limpando o cache do Office antes de executar npm run start e certificando-se de executar npm stop antes de reiniciar o suplemento.

  

Confira também

• Visão geral de funções personalizadas
• Metadados de funções personalizadas
• Tempo de execução de funções personalizadas do Excel
• Usando o Visual Studio Code para publicar