Compartir a través de

Controlar y devolver errores de la función personalizada

  • Artículo

Si algo sale mal mientras se ejecuta la función personalizada, devuelva un error para informar al usuario. Si tiene requisitos de parámetros específicos, como solo números positivos, pruebe los parámetros y genere un error si no son correctos. También puede usar un bloque try...catch para detectar cualquier error que ocurra mientras se ejecuta la función personalizada.

Detectar y devolver un error

Veamos un caso en el que debe asegurarse de que un parámetro de código postal está en el formato correcto para que funcione la función personalizada. La siguiente función personalizada usa una expresión regular para comprobar el código postal. Si el formato del código postal es correcto, buscará la ciudad mediante otra función y devolverá el valor. Si el formato no es válido, la función devuelve un #VALUE! error a la celda.

/**
* 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 se usa para devolver un error a la celda. Al crear el objeto, especifique qué error desea usar eligiendo uno de los siguientes ErrorCode valores de enumeración.

Valor enum ErrorCode Valor de celda de Excel Descripción
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

Además de devolver un único error, una función personalizada puede generar una matriz dinámica que incluya un error. 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 introducir tres parámetros en una función personalizada, reemplazar uno de los parámetros de entrada por un #NUM! error y, a continuación, devolver una matriz 2 dimensiones con los resultados del procesamiento 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]];
}

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

En general, use try...catch bloques en la función personalizada para detectar posibles errores que se produzcan. Si no controla las excepciones en el código, se devolverán a Excel. De forma predeterminada, Excel devuelve #VALUE! errores o excepciones no controladas.

En el código de ejemplo siguiente, la función personalizada realiza una llamada fetch a un servicio REST. Es posible que la llamada no tenga éxito, por ejemplo, si el servicio REST devuelve un error o la red deja de funcionar. Si esto ocurre, la función personalizada volverá #N/A a indicar 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