Share via

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

  • [アーティクル]

カスタム関数の実行中に問題が発生した場合は、エラーを返してユーザーに通知します。 正の数値だけなど、特定のパラメーター要件がある場合は、パラメーターをテストし、正しくない場合はエラーをスローします。 try...catch ブロックを使用して、カスタム関数の実行中に発生したエラーを検出することもできます。

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

カスタム関数が機能するために郵便番号パラメーターが正しい形式であることを確認する必要があるケースを見てみましょう。 次のカスタム関数は、正規表現を使用して郵便番号を確認します。 郵便番号の形式が正しい場合は、別の関数を使用して市区町村を検索し、値を返します。 形式が有効でない場合、関数はセルにエラーを #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;

エラーと #N/A エラーでは#VALUE!、カスタム エラー メッセージもサポートされます。 エラー インジケーター メニューにカスタム エラー メッセージが表示されます。このメニューにアクセスするには、エラーが発生した各セルのエラー フラグをポイントします。 次の例は、エラーを含むカスタム エラー メッセージを返す方法を #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 つのエラーを返すだけでなく、エラーを含む動的配列を出力することもできます。 たとえば、カスタム関数は 配列 [1],[#NUM!],[3]を出力できます。 次のコード サンプルは、カスタム関数に 3 つのパラメーターを入力し、入力パラメーター #NUM! の 1 つをエラーに置き換え、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 メタデータ プロパティ allowErrorForDataTypeAny を に設定する true必要があります。 詳細については、「 カスタム関数の JSON メタデータを手動で作成 する」を参照してください。

重要

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

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

一般に、カスタム関数でブロックを使用 try...catch して、発生する可能性のあるエラーをキャッチします。 コードで例外を処理しない場合は、Excel に返されます。 既定では、Excel は未処理の #VALUE! エラーまたは例外を返します。

次のコードサンプルでは、カスタム関数を使用して REST サービスの呼び出しを行ないます。 たとえば REST サービスがエラーを返したり、ネットワークがダウンした場合には、呼び出しが失敗することもあります。 この場合、カスタム関数は、Web 呼び出しが失敗したことを示すために戻ります #N/A 。

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

次の手順

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

関連項目