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

Artigo
08/06/2024

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étuas licenciadas em volume e posteriores
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 2019 ou anterior no Windows

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.
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.

Problemas comuns e soluções

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 está aguardando a conclusão de uma função personalizada, ele exibe #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 com 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.

Compartilhar via