Share via

Behandeln und Zurückgeben von Fehlern von Ihrer benutzerdefinierten Funktion

  • Artikel

Wenn während der Ausführung Der benutzerdefinierten Funktion ein Fehler auftritt, geben Sie einen Fehler zurück, um den Benutzer zu informieren. Wenn Sie bestimmte Parameteranforderungen haben, z. B. nur positive Zahlen, testen Sie die Parameter, und lösen Sie einen Fehler aus, wenn sie nicht korrekt sind. Sie können auch einen try...catch Block verwenden, um Fehler abzufangen, die während der Ausführung Ihrer benutzerdefinierten Funktion auftreten.

Erkennen und Auslösen eines Fehlers

Sehen wir uns einen Fall an, in dem Sie sicherstellen müssen, dass ein Postleitzahlparameter das richtige Format hat, damit die benutzerdefinierte Funktion funktioniert. Die folgende benutzerdefinierte Funktion verwendet einen regulären Ausdruck, um die Postleitzahl zu überprüfen. Wenn das Postleitzahlformat korrekt ist, wird die Stadt mit einer anderen Funktion gesucht und der Wert zurückgegeben. Wenn das Format ungültig ist, gibt die Funktion einen #VALUE! Fehler an die Zelle zurück.

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

Das Objekt CustomFunctions.Error

Das CustomFunctions.Error-Objekt wird verwendet, um einen Fehler an die Zelle zurückzugeben. Geben Sie beim Erstellen des Objekts an, welchen Fehler Sie verwenden möchten, indem Sie einen der folgenden ErrorCode Enumerationswerte auswählen.

ErrorCode-Enumerationswert Excel-Zellwert Beschreibung
divisionByZero #DIV/0 Die Funktion versucht, durch 0 (null) zu dividieren.
invalidName #NAME? Der Funktionsname enthält einen Tippfehler. Beachten Sie, dass dieser Fehler als Eingabefehler für benutzerdefinierte Funktionen unterstützt wird, jedoch nicht als fehler bei der Ausgabe einer benutzerdefinierten Funktion.
invalidNumber #NUM! Es gibt ein Problem mit einer Zahl in der Formel.
invalidReference #REF! Die Funktion bezieht sich auf eine ungültige Zelle. Beachten Sie, dass dieser Fehler als Eingabefehler für benutzerdefinierte Funktionen unterstützt wird, jedoch nicht als fehler bei der Ausgabe einer benutzerdefinierten Funktion.
invalidValue #VALUE! Ein Wert in der Formel ist vom falschen Typ.
notAvailable #N/A Die Funktion oder der Dienst ist nicht verfügbar.
nullReference #NULL! Die Bereiche in der Formel schneiden sich nicht.

Das folgende Codebeispiel zeigt, wie Sie einen Fehler für eine ungültige Zahl (#NUM!) erstellen und zurückgeben.

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

Die #VALUE! Fehler und #N/A unterstützen auch benutzerdefinierte Fehlermeldungen. Benutzerdefinierte Fehlermeldungen werden im Fehlerindikatormenü angezeigt, auf das zugegriffen wird, indem Sie auf jede Zelle mit einem Fehler auf das Fehlerflag zeigen. Das folgende Beispiel zeigt, wie eine benutzerdefinierte Fehlermeldung mit dem #VALUE! Fehler zurückgegeben wird.

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

Behandeln von Fehlern beim Arbeiten mit dynamischen Arrays

Zusätzlich zur Rückgabe eines einzelnen Fehlers kann eine benutzerdefinierte Funktion ein dynamisches Array ausgeben, das einen Fehler enthält. Beispielsweise könnte eine benutzerdefinierte Funktion das Array [1],[#NUM!],[3]ausgeben. Im folgenden Codebeispiel wird gezeigt, wie Sie drei Parameter in eine benutzerdefinierte Funktion eingeben, einen der Eingabeparameter durch einen #NUM! Fehler ersetzen und dann ein zweidimensionales Array mit den Ergebnissen der Verarbeitung der einzelnen Eingabeparameter zurückgeben.

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

Fehler als benutzerdefinierte Funktionseingaben

Eine benutzerdefinierte Funktion kann auch dann ausgewertet werden, wenn der Eingabebereich einen Fehler enthält. Beispielsweise kann eine benutzerdefinierte Funktion den Bereich A2:A7 als Eingabe verwenden, auch wenn A6:A7 einen Fehler enthält.

Um Eingaben zu verarbeiten, die Fehler enthalten, muss für eine benutzerdefinierte Funktion die JSON-Metadateneigenschaft allowErrorForDataTypeAny auf truefestgelegt sein. Weitere Informationen finden Sie unter Manuelles Erstellen von JSON-Metadaten für benutzerdefinierte Funktionen .

Wichtig

Die allowErrorForDataTypeAny -Eigenschaft kann nur mit manuell erstellten JSON-Metadaten verwendet werden. Diese Eigenschaft funktioniert nicht mit dem automatisch generierten JSON-Metadatenprozess.

Verwenden von try...catch Blöcken

Verwenden Sie try...catch im Allgemeinen Blöcke in Ihrer benutzerdefinierten Funktion, um potenzielle Fehler abzufangen, die auftreten. Wenn Sie Ausnahmen in Ihrem Code nicht behandeln, werden sie an Excel zurückgegeben. Standardmäßig gibt Excel für nicht behandelte Fehler oder Ausnahmen zurück #VALUE! .

Im folgenden Codebeispiel ruft die benutzerdefinierte Funktion einen Abruf eines REST-Diensts ab. Es kann vorkommen, dass der Abruf fehlschlägt, z. B. wenn der Rest-Dienst einen Fehler zurückgibt oder das Netzwerk offline geht. In diesem Fall gibt die benutzerdefinierte Funktion zurück #N/A , um anzugeben, dass der Webaufruf fehlgeschlagen ist.

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

Nächste Schritte

Erfahren Sie, wie Sie Probleme mit Ihren benutzerdefinierten Funktionen behandeln.

Siehe auch