Partager via

Gérer et retourner des erreurs à partir de votre fonction personnalisée

Lorsqu’une fonction personnalisée reçoit une entrée non valide, ne peut pas accéder à une ressource ou ne parvient pas à calculer un résultat, retourne l’erreur Excel la plus spécifique possible. Validez rapidement les paramètres pour qu’ils échouent rapidement et utilisez try...catch des blocs pour transformer les exceptions de bas niveau en erreurs Excel claires.

Détecter et générer une erreur

L’exemple suivant valide un code U.S. ZIP avec une expression régulière avant de continuer. Si le format n’est pas valide, une erreur est générée #VALUE! .

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

Objet CustomFunctions.Error

L’objet CustomFunctions.Error renvoie une erreur à la cellule. Spécifiez l’erreur en choisissant une ErrorCode valeur dans la liste suivante.

Valeur enum ErrorCode Valeur de la cellule Excel Description
divisionByZero #DIV/0 La fonction tente de diviser par zéro.
invalidName #NAME? Il y a une faute de frappe dans le nom de la fonction. Notez que cette erreur est prise en charge en tant qu’erreur d’entrée de fonction personnalisée, mais pas en tant qu’erreur de sortie de fonction personnalisée.
invalidNumber #NUM! Il y a un problème avec un nombre dans la formule.
invalidReference #REF! La fonction fait référence à une cellule non valide. Notez que cette erreur est prise en charge en tant qu’erreur d’entrée de fonction personnalisée, mais pas en tant qu’erreur de sortie de fonction personnalisée.
invalidValue #VALUE! Une valeur dans la formule est du type incorrect.
notAvailable #N/A La fonction ou le service n’est pas disponible.
nullReference #NULL! Les plages de la formule ne se croisent pas.

L’exemple de code suivant montre comment créer et retourner une erreur pour un nombre non valide (#NUM!).

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

Les #VALUE! erreurs et #N/A prennent également en charge les messages d’erreur personnalisés. Les messages d’erreur personnalisés s’affichent dans le menu de l’indicateur d’erreur, accessible en pointant sur l’indicateur d’erreur sur chaque cellule avec une erreur. L’exemple suivant montre comment retourner un message d’erreur personnalisé avec l’erreur #VALUE! .

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

Gérer les erreurs lors de l’utilisation de tableaux dynamiques

Les fonctions personnalisées peuvent retourner des tableaux dynamiques qui incluent des erreurs. Par exemple, une fonction personnalisée peut générer le tableau [1],[#NUM!],[3]. L’exemple de code suivant montre comment passer trois paramètres dans une fonction personnalisée, remplacer un paramètre par une #NUM! erreur, puis retourner un tableau à deux dimensions avec les résultats pour chaque entrée.

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

Erreurs en tant qu’entrées de fonction personnalisée

Une fonction personnalisée peut être évaluée même si la plage d’entrée contient une erreur. Par exemple, une fonction personnalisée peut prendre la plage A2 :A7 comme entrée, même si A6 :A7 contient une erreur.

Pour traiter les entrées qui contiennent des erreurs, une fonction personnalisée doit avoir la propriété allowErrorForDataTypeAny de métadonnées JSON définie sur true. Pour plus d’informations, consultez Créer manuellement des métadonnées JSON pour les fonctions personnalisées .

Importante

La allowErrorForDataTypeAny propriété ne peut être utilisée qu’avec des métadonnées JSON créées manuellement. Cette propriété ne fonctionne pas avec le processus de métadonnées JSON généré automatiquement.

Utiliser des try...catch blocs

Utilisez des try...catch blocs pour intercepter les erreurs potentielles et renvoyer des messages d’erreur significatifs à vos utilisateurs. Par défaut, Excel retourne #VALUE! pour les erreurs ou exceptions non gérées.

Dans l’exemple de code suivant, la fonction personnalisée utilise fetch pour appeler un service REST. Si l’appel échoue, par exemple lorsque le service REST retourne une erreur ou que le réseau n’est pas disponible, la fonction personnalisée retourne #N/A pour indiquer que l’appel web a échoué.

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

Étapes suivantes

Découvrez comment résoudre les problèmes liés à vos fonctions personnalisées.

Voir aussi

  • Last updated on