Compartilhar via

Solução de problemas das funções personalizadas

Ao desenvolver funções personalizadas, você poderá encontrar erros no produto durante a criação e testes das funções.

Importante

Observe que as funções personalizadas do Excel estão disponíveis nas plataformas a seguir.

  • Office na Web
  • Office no Windows
    • Assinatura do Microsoft 365
    • revenda perpétua do Office 2016 e posterior
    • Office 2021 perpétuo/LTSC licenciado em volume e posterior
  • Office no Mac

As funções personalizadas do Excel não são atualmente suportadas no seguinte:

  • Office no iPad
  • versões perpétuas licenciadas em volume do Office 2021 ou anterior no Windows

Observação

O manifesto unificado do Microsoft 365 não suporta atualmente projetos de funções personalizadas. Tem de utilizar o manifesto apenas de suplemento para projetos de funções personalizadas. Para obter mais informações, veja Manifesto de Suplementos do Office.

Para resolver problemas, você pode habilitar o log de tempo de execução para capturar erros e consultar as mensagens de erro nativas do Excel. Alem disso, verifique se há erros comuns, como deixar promessas não resolvidas.

Depurar funções personalizadas

Para depurar suplementos de funções personalizadas que utilizam um runtime partilhado, consulte Descrição geral da depuração de Suplementos do Office.

Para depurar suplementos de funções personalizadas que não utilizam um runtime partilhado, veja Depuração de funções personalizadas.

Habilitar o log de tempo de execução

Se estiver testando o suplemento do Office no Windows, você deverá habilitar o log do tempo de execução. O log de tempo de execução entrega instruções console.log a um arquivo de log separado criado para ajudar você a descobrir problemas. As instruções abrangem uma variedade de erros, incluindo erros relacionados com o ficheiro de manifesto do suplemento, condições de runtime ou instalação das suas funções personalizadas. Para saber mais sobre o log do tempo de execução, confira Depurar seu suplemento com o log do tempo de execução.

Verificar se há mensagens de erro do Excel

O Excel tem diversas mensagens de erro internas que serão retornadas para uma célula se houver um erro de cálculo. As funções personalizadas usam apenas as seguintes mensagens de erro: #NULL!, #DIV/0!, #VALUE!, #REF!, #NAME?, #NUM!, #N/A e #BUSY!.

Geralmente, estes erros correspondem aos erros que você já deve estar familiarizado no Excel. Existem apenas algumas exceções específicas para as funções personalizadas, listadas aqui:

  • Um erro #NAME? geralmente significa que houve um problema ao registrar as suas funções. Para obter informações adicionais, consulte o erro Funções personalizadas que mostram #NAME?.
  • Um erro #N/A também pode ser um sinal de que esta função, embora registrada, não pode ser executada. Isto é normalmente devido à um comando CustomFunctions.associate em falta.
  • Um #VALUE! erro normalmente indica um erro no arquivo de script das funções.
  • Um erro #REF! pode indicar que o nome da sua função é o mesmo nome de uma função em um suplemento já existente.

Limpar o cache do Office

Informações sobre funções personalizadas são armazenadas em cache pelo Office. Às vezes, ao desenvolver e recarregar repetidamente um suplemento com funções personalizadas, as suas alterações podem não aparecer. Isso pode ser corrigido limpando o cache do Office. Para saber mais, confira Limpar o cache do Office.

Limpar a cache de funções personalizadas quando o suplemento é executado

Por vezes, poderá ter de limpar a cache de funções personalizadas para um suplemento implementado para os utilizadores finais, para que as atualizações de suplementos e as alterações de definição de funções personalizadas sejam incorporadas ao mesmo tempo. Sem acionar uma cache de funções personalizadas, as alterações aos ficheiros functions.json e functions.js podem demorar até 24 horas a chegar aos utilizadores finais, enquanto as alterações efetuadas aos taskpane.html chegar aos utilizadores finais mais rapidamente.

Observação

Assim que esta definição estiver ativada para um documento, entrará em vigor da próxima vez que o documento for aberto com o suplemento. Não se aplica imediatamente após a função ser chamada.

Para garantir que a cache de funções personalizadas é limpa pelo suplemento, adicione o seguinte código ao ficheiro functions.js e, em seguida, chame o setForceRefreshOn método na sua Office.onReady chamada ou noutra lógica de inicialização do suplemento.

Importante

Este processo para limpar a cache de funções personalizadas só é suportado para suplementos de funções personalizadas que utilizem um runtime partilhado.

// To enable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOn` method in your `Office.onReady` call.
function setForceRefreshOn() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        true  
    );  
    Office.context.document.settings.saveAsync();  
}

Dica

Atualizar frequentemente a cache de funções personalizadas pode afetar o desempenho, pelo que limpar a cache de funções personalizadas com setForceRefreshOn só deve ser utilizado durante o desenvolvimento do suplemento ou para resolve erros. Assim que um suplemento de funções personalizadas estiver estabilizado, pare de forçar as atualizações da cache.

Para desativar a cache das funções personalizadas no suplemento, defina Office.ForceRefreshCustomFunctionsCache como false e chame o método na chamada Office.onReady . O seguinte exemplo de código mostra um exemplo com um setForceRefreshOff método .

// To disable custom functions cache clearing, add this method to your functions.js 
// file, and then call the `setForceRefreshOff` method in your `Office.onReady` call.
function setForceRefreshOff() {  
    Office.context.document.settings.set(  
        'Office.ForceRefreshCustomFunctionsCache',
        false  
    );  
    Office.context.document.settings.saveAsync();  
}

Problemas comuns e soluções

Funções personalizadas a mostrar #NAME? erro

Ao abrir um livro que utiliza um suplemento de funções personalizadas, por vezes é apresentado um #NAME? erro nas células de função personalizadas em vez do resultado da fórmula. O IntelliSense para funções personalizadas também pode não aparecer no livro ao criar novas fórmulas. A causa provável deste problema é o facto de o suplemento de funções personalizadas não ter sido registado com êxito.

Para resolve o problema, experimente as seguintes abordagens:

Não é possível abrir o suplemento a partir do localhost: utilizar uma isenção de loopback local

Se vir o erro "Não é possível abrir este suplemento a partir do localhost", terá de ativar uma isenção de loopback local. Para obter detalhes sobre como fazer isso, confira este artigo de suporte da Microsoft.

Relatórios de log de tempo de execução "TypeError: Falha na solicitação de rede" no Excel para Windows

Se você ver o erro "TypeError: Falha na solicitação de rede" em seu log de tempo de execução enquanto faz chamadas para seu servidor localhost, você precisará habilitar uma exceção de loopback local. Para mais detalhes sobre como fazer isso, confira Opção #2 neste artigo de suporte da Microsoft .

Garantir que as promessas retornem resultados

Quando o Excel aguarda a conclusão de uma função personalizada, esta é apresentada #BUSY! na célula. Se o código da função personalizada retornar uma promessa, mas a promessa não retornar um resultado, o Excel continuará exibindo #BUSY!. Verifique suas funções para garantir que as promessas estejam retornando corretamente um resultado para uma célula.

Erro: O servidor de desenvolvimento já está em execução na porta 3000

Às vezes, ao executar npm start você poderá ver um erro que o servidor de desenvolvimento já está executando na porta 3000 (ou qualquer outra porta que o seu suplemento use). Você pode parar o servidor de desenvolvimento executando npm stop ou fechando a janela Node.js. Em alguns casos, pode demorar alguns minutos até que o servidor dev deixe de ser executado.

Minhas funções não carregam: associar funções

Nos casos em que seu JSON não tiver sido registrado e você tiver criado os seus próprios metadados JSON, talvez receba um #VALUE!erro ou receba uma notificação de que o seu suplemento não pode ser carregado. Geralmente, isso significa que você precisa associar cada função personalizada a idpropriedade especificada no arquivo de metadados JSON. Isto é feito com a CustomFunctions.associate() função . Normalmente, esta chamada de função é feita após cada função ou no final do ficheiro de script. Se uma função personalizada não estiver associada, ele não funcionará.

O exemplo a seguir mostra uma função add, seguida pelo nome add da função que está sendo associada a ADD da id JSON correspondente.

/**
 * Add two numbers.
 * @customfunction
 * @param {number} first First number.
 * @param {number} second Second number.
 * @returns {number} The sum of the two numbers.
 */
function add(first, second) {
  return first + second;
}

CustomFunctions.associate("ADD", add);

Para obter mais informações sobre este processo, veja Associar nomes de funções a metadados JSON.

Problemas conhecidos

Os problemas conhecidos são monitorizados e comunicados no repositório do GitHub das Funções Personalizadas do Excel.

Fornecer comentários

Se você tiver problemas que não estão descritos aqui, fale conosco. Há duas maneiras de relatar problemas.

No Excel no Windows ou no Mac

Se estiver a utilizar o Excel no Windows ou no Mac, pode comunicar feedback à equipa de extensibilidade do Office diretamente a partir do Excel. Para fazer isso, selecione Arquivo>Comentário>Enviar um Rosto Triste. Enviando um Rosto Triste, você fornece os registros necessários para entendermos o problema que você está enfrentando.

No Github

Sinta-se à vontade para enviar problemas encontrados através do recurso "Comentários do conteúdo" na parte inferior de todas as páginas de documentação ou informe um novo problema diretamente no repositório de funções personalizadas.

Próximas etapas

Saiba como tornar as suas funções personalizadas compatíveis com as funções definidas pelo usuário de XLL.

Confira também

  • Last updated on