Manipular e retornar erros da função personalizada

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

Detectar e lançar um erro

O exemplo a seguir valida um código U.S. ZIP com uma expressão regular antes de continuar. Se o formato for inválido, ele gerará 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 retorna um erro à célula. Especifique qual erro escolhendo um ErrorCode valor na lista a seguir.

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 personalizada.
invalidNumber #NUM! Há um problema com um número na fórmula.
invalidReference #REF! A função se refere 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 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 formam uma interseção.

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. Mensagens de erro personalizadas são exibidas no menu indicador de erro, que é acessado passando o mouse 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

As funções personalizadas podem retornar matrizes dinâmicas que incluem erros. Por exemplo, uma função personalizada pode gerar a matriz [1],[#NUM!],[3]. O exemplo de código a seguir mostra como passar três parâmetros para uma função personalizada, substituir um parâmetro por um #NUM! erro e, em seguida, retornar 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ção personalizada

Uma função personalizada pode avaliar até mesmo se o intervalo de entrada contém um erro. Por exemplo, uma função personalizada pode usar o intervalo A2:A7 como entrada, mesmo que 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 manualmente metadados JSON 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

Use try...catch blocos para detectar possíveis erros e retornar mensagens de erro significativas aos usuários. 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 usa fetch para chamar um serviço REST. Se a chamada falhar, como quando o serviço REST retorna um erro ou a rede não está disponível, a função personalizada retorna #N/A para mostrar que a chamada da 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