Freigeben über

Behandeln und Zurückgeben von Fehlern von Ihrer benutzerdefinierten Funktion

Wenn eine benutzerdefinierte Funktion ungültige Eingaben empfängt, nicht auf eine Ressource zugreifen kann oder ein Ergebnis nicht berechnet werden kann, gibt den spezifischsten Excel-Fehler zurück, den Sie können. Überprüfen Sie Parameter frühzeitig, damit sie sofort fehlschlagen, und verwenden Sie try...catch Blöcke, um Ausnahmen auf niedriger Ebene in klare Excel-Fehler umzuwandeln.

Erkennen und Auslösen eines Fehlers

Im folgenden Beispiel wird eine U.S. ZIP Code mit einem regulären Ausdruck überprüft, bevor Sie fortfahren. Wenn das Format ungültig ist, wird ein #VALUE! Fehler ausgelöst.

/**
* 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 gibt einen Fehler an die Zelle zurück. Geben Sie den Fehler an, indem Sie einen ErrorCode Wert aus der folgenden Liste 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

Benutzerdefinierte Funktionen können dynamische Arrays zurückgeben, die Fehler enthalten. Beispielsweise könnte eine benutzerdefinierte Funktion das Array [1],[#NUM!],[3]ausgeben. Das folgende Codebeispiel zeigt, wie Sie drei Parameter an eine benutzerdefinierte Funktion übergeben, einen Parameter durch einen #NUM! Fehler ersetzen und dann ein zweidimensionales Array mit den Ergebnissen für jede Eingabe 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 Blöcke, um potenzielle Fehler abzufangen und aussagekräftige Fehlermeldungen an Ihre Benutzer zurückzugeben. Standardmäßig gibt Excel für nicht behandelte Fehler oder Ausnahmen zurück #VALUE! .

Im folgenden Codebeispiel verwendet die benutzerdefinierte Funktion fetch, um einen REST-Dienst aufzurufen. Wenn der Aufruf fehlschlägt, z. B. wenn der REST-Dienst einen Fehler zurückgibt oder das Netzwerk nicht verfügbar ist, gibt die benutzerdefinierte Funktion zurück #N/A , um anzuzeigen, 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

  • Last updated on