Compartilhar via

Manipular e retornar erros de sua função personalizada

  • Artigo

Se algo der errado enquanto sua função personalizada for executada, retorne um erro para informar o usuário. Se você tiver requisitos de parâmetro específicos, como apenas números positivos, teste os parâmetros e lance um erro se eles não estiverem corretos. Você também pode usar um bloco try...catch para detectar quaisquer erros que ocorram enquanto sua função personalizada é executada.

Detectar e lançar um erro

Vamos examinar um caso em que você precisa garantir que um parâmetro de CEP esteja no formato correto para que a função personalizada funcione. A função personalizada a seguir usa uma expressão regular para verificar o CEP. Se o formato de CEP estiver correto, ele procurará a cidade usando outra função e retornará o valor. Se o formato não for válido, a função retornará um #VALUE! erro para a célula.

/**
* 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 é usado para retornar um erro de volta à célula. Ao criar o objeto, especifique qual erro você deseja usar escolhendo um dos valores de enumeração a seguir ErrorCode .

Valor de enumeração ErrorCode Valor da célula do Excel Descrição
divisionByZero #DIV/0 A função está tentando dividir por zero.
invalidName #NAME? Há um erro de digitação no nome da função. Observe que esse erro tem suporte como um erro de entrada de função personalizada, mas não como um erro de saída de função personalizado.
invalidNumber #NUM! Há um problema com um número na fórmula.
invalidReference #REF! A função refere-se a uma célula inválida. Observe que esse erro tem suporte como um erro de entrada de função personalizada, mas não como um erro de saída de função personalizado.
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 dão suporte a mensagens de erro personalizadas. As mensagens de erro personalizadas são exibidas no menu indicador de erro, que é acessado pairando sobre o sinalizador de erro em cada célula com um erro. O exemplo a seguir mostra como retornar 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;

Manipular erros ao trabalhar com matrizes dinâmicas

Além de retornar um único erro, uma função personalizada pode gerar uma matriz dinâmica que inclui um erro. Por exemplo, uma função personalizada pode gerar a matriz [1],[#NUM!],[3]. O exemplo de código a seguir mostra como inserir três parâmetros em uma função personalizada, substituir um dos parâmetros de entrada por um #NUM! erro e retornar uma matriz bidimensional com os resultados do processamento de cada parâmetro de 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ção personalizada

Uma função personalizada pode ser avaliada mesmo se o intervalo de entrada contiver um erro. Por exemplo, uma função personalizada pode usar o intervalo A2:A7 como uma entrada, mesmo que a A6:A7 contenha um erro.

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

Importante

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

Usar try...catch blocos

Em geral, use try...catch blocos em sua função personalizada para capturar possíveis erros que ocorram. Se você não lidar com exceções em seu código, elas serão retornadas ao Excel. Por padrão, o Excel retorna #VALUE! para erros ou exceções não tratados.

No exemplo de código a seguir, a função personalizada faz uma chamada de busca para um serviço REST. É possível que a chamada falhe, por exemplo, se o serviço REST retornar um erro ou a rede cair. Se isso acontecer, a função personalizada retornará #N/A para indicar 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