次の方法で共有

カスタム関数のエラーを処理して返す

カスタム関数が無効な入力を受け取った場合、リソースにアクセスできない場合、または結果の計算に失敗した場合は、可能な最も具体的な Excel エラーを返します。 パラメーターを早期に検証してすぐに失敗し、 try...catch ブロックを使用して低レベルの例外を明確な Excel エラーに変換します。

エラーを検出してスローする

次の例では、続行する前に、正規表現を使用して U.S. ZIP Code を検証します。 形式が無効な場合は、 #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;
}

The CustomFunctions.Error object

CustomFunctions.Error オブジェクトは、セルにエラーを返します。 次の一覧から ErrorCode 値を選択して、エラーを指定します。

ErrorCode enum value Excel のセル値 説明
divisionByZero #DIV/0 関数が 0 で除算しようとしています。
invalidName #NAME? 関数名に入力ミスがあります。 このエラーはカスタム関数入力エラーとしてサポートされていますが、カスタム関数出力エラーとしてサポートされていないことに注意してください。
invalidNumber #NUM! 数式の数値に問題があります。
invalidReference #REF! 関数は無効なセルを参照します。 このエラーはカスタム関数入力エラーとしてサポートされていますが、カスタム関数出力エラーとしてサポートされていないことに注意してください。
invalidValue #VALUE! 数式の値が正しくない型です。
notAvailable #N/A 関数またはサービスは使用できません。
nullReference #NULL! 数式内の範囲が交差しません。

次のコードサンプルは、無効な番号 (#NUM!) に対してエラーを作成して返す方法を示しています。

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

#VALUE!エラーと#N/A エラーは、カスタム エラー メッセージもサポートします。 エラー インジケーター メニューにカスタム エラー メッセージが表示されます。このメニューにアクセスするには、エラーが発生した各セルのエラー フラグをポイントします。 次の例は、 #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;

動的配列を操作するときにエラーを処理する

カスタム関数は、エラーを含む動的配列を返すことができます。 たとえば、カスタム関数は配列 [1],[#NUM!],[3]を出力できます。 次のコード サンプルは、3 つのパラメーターをカスタム関数に渡し、1 つのパラメーターを #NUM! エラーに置き換え、2 次元配列を各入力の結果で返す方法を示しています。

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

カスタム関数入力としてのエラー

カスタム関数は、入力範囲にエラーが含まれている場合でも評価できます。 たとえば、A6 :A7 にエラーが含まれている場合でも、カスタム関数は範囲 A2:A7 を入力として受け取ることができます。

エラーを含む入力を処理するには、カスタム関数で JSON メタデータ プロパティを true に設定allowErrorForDataTypeAny必要があります。 詳細については、「 カスタム関数の JSON メタデータを手動で作成 する」を参照してください。

重要

allowErrorForDataTypeAny プロパティは、手動で作成された JSON メタデータでのみ使用できます。 このプロパティは、自動生成された JSON メタデータ プロセスでは機能しません。

try...catch ブロックを使用する

try...catch ブロックを使用して、潜在的なエラーをキャッチし、意味のあるエラー メッセージをユーザーに返します。 既定では、未処理のエラーまたは例外の #VALUE! が返されます。

次のコード サンプルでは、カスタム関数は fetch を使用して REST サービスを呼び出します。 REST サービスがエラーを返したときやネットワークが使用できない場合など、呼び出しが失敗した場合、カスタム関数は #N/A を返して 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);
    })
}

次の手順

自分のカスタム関数で問題をトラブルシューティングを行う方法についての詳細を確認する。

関連項目

  • Last updated on