Compartilhar via

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 transferir e instalar a versão certa para o seu sistema operativo.

  • 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 ainda não tiver o Office, poderá qualificar-se para uma subscrição de programador Microsoft 365 E5 através do Programa para Programadores do Microsoft 365. Para obter detalhes, consulte as FAQ. Em alternativa, pode inscrever-se numa avaliação gratuita de um 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. Será adicionada uma pasta que contém o projeto 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
    • Qual é o nome do seu suplemento?My custom functions add-in

    A interface de linha de comandos do Gerador de suplementos yeoman do Office pede 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 suplemento no Excel na Web, execute o seguinte comando. O servidor Web local será iniciado ao executar este comando. Substitua “{url}” pelo URL de um documento do Excel no seu OneDrive ou uma biblioteca do SharePoint para a qual você tenha permissões.

Observação

Se estiver a desenvolver num Mac, coloque as {url} aspas simples. Não o faça no Windows.

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

Eis alguns exemplos.

  • npm run start:web -- --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
  • npm run start:web -- --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
  • npm run start:web -- --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

Se o seu suplemento não carregar em sideload no documento, carregue-o manualmente ao seguir as instruções em Suplementos de sideload manualmente para Office na Web.

Observação

  • Os Suplementos do Office devem utilizar HTTPS e não HTTP, mesmo quando estiver a desenvolver. Se lhe for pedido para instalar um certificado depois de executar um dos seguintes comandos, aceite o pedido 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.

  • Se esta for a primeira vez que desenvolve um Suplemento do Office no seu computador, poderá ser-lhe pedido na linha de comandos para conceder ao Microsoft Edge WebView uma isenção de loopback ("Permitir loopback localhost para o Microsoft Edge WebView?"). Quando lhe for pedido, introduza Y para permitir a isenção. Tenha em atenção que precisará de privilégios de administrador para permitir a isenção. Uma vez permitido, não lhe deverá ser pedida uma isenção quando carregar os Suplementos do Office no futuro (a menos que remova a isenção do seu computador). Para saber mais, consulte "Não é possível abrir este suplemento a partir do localhost" ao carregar um Suplemento do Office ou ao utilizar o Fiddler.

    A linha de comandos na linha de comandos para permitir ao Microsoft Edge WebView uma isenção de loopback.

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. No Excel , selecione>Suplementos Base e, em seguida, selecione Mais Suplementos.

  2. No separador OS MEUS SUPLEMENTOS , selecione Gerir Os Meus Suplementos e escolha Carregar o Meu Suplemento.

  3. Escolha Procurar... e navegue até o diretório raiz do projeto criado pelo gerador Yeoman.

  4. Selecione o arquivo manifest. XML e escolha abrir, escolha Carregar.

  5. Agora, vamos experimentar a nova função. Na célula B1, digite o texto =CONTOSO. GETSTARCOUNT("OfficeDev", "Excel-Custom-Functions") e pressione Enter. Você deve ver que o resultado na célula B1 é o número atual de estrelas fornecido para o repositório do GitHub de funções personalizadas do Excel.

Quando 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 tiver utilizado npm start, o seguinte comando também desinstala o suplemento.

    npm stop

  • Se tiver carregado manualmente o suplemento em sideload, consulte Remover um suplemento sideloaded.

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

  • O passo automático npm install que o Yo Office executa pode falhar. Se vir erros ao tentar executar npm start, navegue para a pasta do projeto recentemente criada numa linha de comandos e execute npm installmanualmente . Para obter mais informações sobre o Yo Office, consulte Criar projetos de Suplementos do Office com o Yeoman Generator.

  • 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. Pode impedir esta situação ao limpar a cache do Office antes de executar npm run start e certificar-se de que é executada npm stop antes de reiniciar o suplemento.

    Uma mensagem de erro Excel intitulada

Confira também