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

  • Artigo

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 mais recente de LTS). Visite o siteNode.js para baixar e instalar a versão certa para 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 tiver o Office, poderá se qualificar para uma assinatura de desenvolvedor Microsoft 365 E5 por meio do Programa de Desenvolvedor do Microsoft 365; para obter detalhes, confira as perguntas frequentes. Como alternativa, você pode se inscrever para uma avaliação gratuita de 1 mês ou comprar 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
    • O que você deseja nomear seu suplemento?My custom functions add-in

    A interface da linha de comando do gerador de suplementos do Yeoman Office solicita projetos de funções personalizadas.

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

  2. O gerador Yeoman fornecerá algumas instruções na linha de comando sobre o que fazer com o projeto, mas ignore-as e continue seguindo nossas instruções. 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.

Para testar o seu suplemento no Excel para Windows ou Mac, execute o seguinte comando. Quando você executa este comando, o servidor Web local iniciará e o Excel abrirá com o seu suplemento carregado.

npm run start:desktop

Observação

Os suplementos do Office devem usar HTTPS, não HTTP, mesmo enquanto você estiver desenvolvendo. Se você for solicitado a instalar um certificado depois de executar um dos comandos a seguir, aceite o prompt para instalar o certificado que o gerador Yeoman fornece. Você também pode executar o prompt de comando ou terminal como administrador para que as alterações sejam feitas.

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. Executar a função CONTOSO.ADD, usando os 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. Digitando =CONTOSO.ADD(10,200) deve obter o resultado 210 na célula, depois 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.

  1. Na faixa de opções do Excel , selecione>Suplementos internos.

  2. Na seção Suplementos do Desenvolvedor , selecione Meu suplemento de funções personalizadas para registrá-lo .

    A caixa de diálogo Meus Suplementos que mostra suplementos ativos, com o botão suplemento Minha função personalizada realçado.

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.

Tutorial de funções personalizadas do Excel

Solução de problemas

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 impedir isso limpando o cache Office antes de executar npm run start.

Uma mensagem de erro Excel intitulada

Confira também