Compartilhar via

Processar e devolver erros da sua função personalizada

Quando uma função personalizada recebe uma entrada inválida, não consegue aceder a um recurso ou não consegue calcular um resultado, devolve o erro mais específico do Excel que pode. Valide os parâmetros antecipadamente para falhar rapidamente e utilize try...catch blocos para transformar exceções de baixo nível em erros claros do Excel.

Detectar e lançar um erro

O exemplo seguinte valida um código de U.S. ZIP com uma expressão regular antes de continuar. Se o formato for inválido, gera um #VALUE! erro.

/**
* Gets a city name for the given U.S. ZIP Code.
* @customfunction
* @param {string} zipCode
* @returns The city of the ZIP Code.
*/
function getCity(zipCode: string): string {
  let isValidZip = /(^\d{5}$)|(^\d{5}-\d{4}$)/.test(zipCode);
  if (isValidZip) return cityLookup(zipCode);
  let error = new CustomFunctions.Error(CustomFunctions.ErrorCode.invalidValue, "Please provide a valid U.S. zip code.");
  throw error;
}

O objeto CustomFunctions.Error

O objeto CustomFunctions.Error devolve um erro à célula. Especifique o erro ao escolher um ErrorCode valor na lista seguinte.

Valor de enumeração ErrorCode Valor da célula do Excel Descrição
divisionByZero #DIV/0 A função está a tentar dividir por zero.
invalidName #NAME? Existe um erro de digitação no nome da função. Tenha em atenção que este erro é suportado como um erro de entrada de função personalizada, mas não como um erro de saída da função personalizada.
invalidNumber #NUM! Existe um problema com um número na fórmula.
invalidReference #REF! A função refere-se a uma célula inválida. Tenha em atenção que este erro é suportado como um erro de entrada de função personalizada, mas não como um erro de saída da função personalizada.
invalidValue #VALUE! Um valor na fórmula é do tipo errado.
notAvailable #N/A A função ou serviço não está disponível.
nullReference #NULL! Os intervalos na fórmula não se cruzam.

O exemplo de código a seguir mostra como criar e retornar um erro para um número inválido (#NUM!).

let error = new CustomFunctions.Error(CustomFunctions.ErrorCode.invalidNumber);
throw error;

Os #VALUE! erros e #N/A também suportam mensagens de erro personalizadas. As mensagens de erro personalizadas são apresentadas no menu do indicador de erro, que é acedido ao pairar o rato sobre o sinalizador de erro em cada célula com um erro. O exemplo seguinte mostra como devolver uma mensagem de erro personalizada com o #VALUE! erro.

// You can only return a custom error message with the #VALUE! and #N/A errors.
let error = new CustomFunctions.Error(CustomFunctions.ErrorCode.invalidValue, "The parameter can only contain lowercase characters.");
throw error;

Processar erros ao trabalhar com matrizes dinâmicas

As funções personalizadas podem devolver matrizes dinâmicas que incluem erros. Por exemplo, uma função personalizada pode produzir a matriz [1],[#NUM!],[3]. O seguinte exemplo de código mostra como transmitir três parâmetros para uma função personalizada, substituir um parâmetro por um #NUM! erro e, em seguida, devolver uma matriz bidimensional com os resultados de cada entrada.

/**
* Returns the #NUM! error as part of a 2-dimensional array.
* @customfunction
* @param {number} first First parameter.
* @param {number} second Second parameter.
* @param {number} third Third parameter.
* @returns {number[][]} Three results, as a 2-dimensional array.
*/
function returnInvalidNumberError(first, second, third) {
  // Use the `CustomFunctions.Error` object to retrieve an invalid number error.
  const error = new CustomFunctions.Error(
    CustomFunctions.ErrorCode.invalidNumber, // Corresponds to the #NUM! error in the Excel UI.
  );

  // Enter logic that processes the first, second, and third input parameters.
  // Imagine that the second calculation results in an invalid number error. 
  const firstResult = first;
  const secondResult =  error;
  const thirdResult = third;

  // Return the results of the first and third parameter calculations and a #NUM! error in place of the second result. 
  return [[firstResult], [secondResult], [thirdResult]];
}

Erros como entradas de funções personalizadas

Uma função personalizada pode avaliar mesmo que o intervalo de entrada contenha um erro. Por exemplo, uma função personalizada pode utilizar o intervalo A2:A7 como uma entrada, mesmo que A6:A7 contenha um erro.

Para processar entradas que contenham erros, uma função personalizada tem de ter a propriedade allowErrorForDataTypeAny de metadados JSON definida como true. Veja Criar metadados JSON manualmente para funções personalizadas para obter mais informações.

Importante

A allowErrorForDataTypeAny propriedade só pode ser utilizada com metadados JSON criados manualmente. Esta propriedade não funciona com o processo de metadados JSON gerados automaticamente.

Utilizar try...catch blocos

Utilize try...catch blocos para detetar potenciais erros e devolver mensagens de erro significativas aos seus utilizadores. Por predefinição, o Excel devolve #VALUE! para erros ou exceções não processados.

No seguinte exemplo de código, a função personalizada utiliza a obtenção para chamar um serviço REST. Se a chamada falhar, como quando o serviço REST devolve um erro ou a rede está indisponível, a função personalizada regressa #N/A para mostrar que a chamada Web falhou.

/**
 * Gets a comment from the hypothetical contoso.com/comments API.
 * @customfunction
 * @param {number} commentID ID of a comment.
 */
function getComment(commentID) {
  let url = "https://www.contoso.com/comments/" + commentID;
  return fetch(url)
    .then(function (data) {
      return data.json();
    })
    .then(function (json) {
      return json.body;
    })
    .catch(function (error) {
      throw new CustomFunctions.Error(CustomFunctions.ErrorCode.notAvailable);
    })
}

Próximas etapas

Saiba como solucionar problemas com as suas funções personalizadas.

Confira também

  • Last updated on