カスタム関数のエラーを処理して返す
カスタム関数の実行中に問題が発生した場合は、エラーを返してユーザーに通知します。 正の数値だけなど、特定のパラメーター要件がある場合は、パラメーターをテストし、正しくない場合はエラーをスローします。 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);
})
}
次の手順
自分のカスタム関数で問題をトラブルシューティングを行う方法についての詳細を確認する。
関連項目
Office Add-ins