Compartir a través de

Controlar y devolver errores de la función personalizada

Cuando una función personalizada recibe una entrada no válida, no puede acceder a un recurso o no puede calcular un resultado, devuelve el error de Excel más específico que pueda. Valide los parámetros antes de que se produzca un error rápidamente y use try...catch bloques para convertir excepciones de bajo nivel en errores claros de Excel.

Detectar y devolver un error

En el ejemplo siguiente se valida un código de U.S. ZIP con una expresión regular antes de continuar. Si el formato no es válido, se produce un #VALUE! error.

/**
* 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;
}

El objeto CustomFunctions.Error

El objeto CustomFunctions.Error devuelve un error a la celda. Especifique qué error elige un ErrorCode valor de la lista siguiente.

Valor enum ErrorCode Valor de celda de Excel Description
divisionByZero #DIV/0 La función está intentando dividir por cero.
invalidName #NAME? Hay un error tipográfico en el nombre de la función. Tenga en cuenta que este error se admite como un error de entrada de función personalizada, pero no como un error de salida de función personalizada.
invalidNumber #NUM! Hay un problema con un número en la fórmula.
invalidReference #REF! La función hace referencia a una celda no válida. Tenga en cuenta que este error se admite como un error de entrada de función personalizada, pero no como un error de salida de función personalizada.
invalidValue #VALUE! Un valor de la fórmula es del tipo incorrecto.
notAvailable #N/A La función o el servicio no están disponibles.
nullReference #NULL! Los intervalos de la fórmula no se intersecan.

El siguiente ejemplo de código muestra cómo crear y devolver un error para un número incorrecto (#NUM!).

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

Los #VALUE! errores y #N/A también admiten mensajes de error personalizados. Los mensajes de error personalizados se muestran en el menú del indicador de error, al que se accede al mantener el puntero sobre la marca de error de cada celda con un error. En el ejemplo siguiente se muestra cómo devolver un mensaje de error personalizado con el #VALUE! error.

// 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;

Controlar errores al trabajar con matrices dinámicas

Las funciones personalizadas pueden devolver matrices dinámicas que incluyen errores. Por ejemplo, una función personalizada podría generar la matriz [1],[#NUM!],[3]. En el ejemplo de código siguiente se muestra cómo pasar tres parámetros a una función personalizada, reemplazar un parámetro por un #NUM! error y, a continuación, devolver una matriz bidimensional con los 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]];
}

Errores como entradas de función personalizadas

Una función personalizada puede evaluarse incluso si el intervalo de entrada contiene un error. Por ejemplo, una función personalizada puede tomar el intervalo A2:A7 como entrada, incluso si A6:A7 contiene un error.

Para procesar entradas que contienen errores, una función personalizada debe tener la propiedad allowErrorForDataTypeAny de metadatos JSON establecida en true. Consulte Creación manual de metadatos JSON para funciones personalizadas para obtener más información.

Importante

La allowErrorForDataTypeAny propiedad solo se puede usar con metadatos JSON creados manualmente. Esta propiedad no funciona con el proceso de metadatos JSON generados automáticamente.

Usar try...catch bloques

Use try...catch bloques para detectar posibles errores y devolver mensajes de error significativos a los usuarios. De forma predeterminada, Excel devuelve #VALUE! errores o excepciones no controladas.

En el ejemplo de código siguiente, la función personalizada usa fetch para llamar a un servicio REST. Si se produce un error en la llamada, como cuando el servicio REST devuelve un error o la red no está disponible, la función personalizada vuelve #N/A a mostrar que se produjo un error en la llamada web.

/**
 * 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);
    })
}

Siguientes pasos

Obtenga información sobre cómo solucionar problemas con las funciones personalizadas.

Vea también

  • Last updated on