アプリケーション固有の JavaScript API によるエラー処理

アプリケーション固有の Office JavaScript API を使用してアドインをビルドする場合は、実行時エラーを考慮に入れるエラー処理ロジックを必ず含めてください。 API の非同期的な性質のため、これを行うことは非常に重要です。

ベスト プラクティス

コード サンプルとScript Lab スニペットでは、Excel.run、PowerPoint.run、または Word.run を呼び出すたびに、エラーをキャッチするための catch ステートメントが付随していることがわかります。 アプリケーション固有の API を使用してアドインをビルドする場合も、同じパターンを使用することをお勧めします。

$("#run").on("click", () => tryCatch(run));

async function run() {
  await Excel.run(async (context) => {
      // Add your Excel JavaScript API calls here.

      // Await the completion of context.sync() before continuing.
    await context.sync();
    console.log("Finished!");
  });
}

/** Default helper for invoking an action and handling errors. */
async function tryCatch(callback) {
  try {
    await callback();
  } catch (error) {
    // Note: In a production add-in, you'd want to notify the user through your add-in's UI.
    console.error(error);
  }
}

API エラー

Office JavaScript API 要求が正常に実行されない場合、API は次のプロパティを含むエラー オブジェクトを返します。

  • コード: エラー メッセージの code プロパティには、OfficeExtension.ErrorCodes または {application}.ErrorCodes の一部である文字列が含まれます。{application} は Excel、PowerPoint、または Word を表します。 たとえば、エラー コード "InvalidReference" は、参照が指定された操作に対して有効でないことを示します。 エラー コードはローカライズされません。

  • message: エラー メッセージの message プロパティには、ローカライズされた文字列のエラーの概要が含まれています。 このエラー メッセージは、エンド ユーザーによる使用を意図したものではありません。エラー コードと適切なビジネス ロジックを使用して、アドインがエンド ユーザーに対して表示するエラー メッセージを特定する必要があります。

  • debugInfo:存在する場合、エラー メッセージの debugInfo プロパティは、エラーの根本原因を理解するために使用できる追加情報を提供します。

注:

console.log() を使用してエラー メッセージを本体に出力する場合、それらのメッセージはサーバーにのみ表示されます。 エンド ユーザーには、アドインの作業ウィンドウや Office アプリケーションのどこにもこれらのエラー メッセージは表示されません。 ユーザーにエラーを報告するには、「 エラー通知」を参照してください。

エラー コードとメッセージ

次の表は、アプリケーション固有の API が返す可能性があるエラーの一覧です。

注:

次の表では、アプリケーション固有の API の使用中に発生する可能性があるエラー メッセージを示します。 共通 API を使用している場合は、「 Office 共通 API エラー コード 」を参照して、関連するエラー メッセージを確認してください。

エラー コード エラー メッセージ 備考
AccessDenied 要求された操作を実行できません。 これは、ユーザーのウイルス対策ソフトウェアが Office の一部をブロックしていることが原因である可能性があります。 より詳細なガイダンスについては、「エラー: アクセスが拒否されました」の 一般的なエラーとトラブルシューティングの手順 を参照してください。
ActivityLimitReached アクティビティの制限に達しました。 なし
ApiNotAvailable 要求された API は使用できません。 なし
ApiNotFound 使用しようとしている API が見つかりませんでした。 新しいバージョンの Office アプリケーションで利用できる場合があります。 詳細については、「 Office アドインの Office クライアント アプリケーションとプラットフォームの可用性 」を参照してください。 なし
BadPassword 指定したパスワードが正しくありません。 なし
Conflict 競合のため、要求を処理できませんでした。 なし
ContentLengthRequired Content-length HTTP ヘッダーがありません。 なし
GeneralException 要求の処理中に内部エラーが発生しました。 なし
HostRestartNeeded Office アプリケーションを再起動する必要があります。 このエラーは、Office アプリケーションの起動後にこのメソッドを呼び出すアドインが更新されている場合、 Office.ribbon.requestUpdate() メソッドによってスローされます。
InsertDeleteConflict 試行された挿入操作または削除操作で競合が発生しました。 なし
InvalidArgument 引数が無効であるか、存在しません。または形式が正しくありません。 なし
InvalidBinding このオブジェクトのバインドは、以前の更新プログラムが原因で無効になっています。 なし
InvalidOperation 試行された操作は、このオブジェクトでは無効です。 なし
InvalidReference この参照は、現在の操作に対して無効です。 なし
InvalidRequest 要求を処理できません。 なし
InvalidRibbonDefinition Office に無効なリボン定義が付与されました。 このエラーは、無効な RibbonUpdateObject が Office.ribbon.requestUpdate() メソッドに渡された場合にスローされます。
InvalidSelection 現在の選択内容は、この操作では無効です。 なし
ItemAlreadyExists 作成中のリソースはすでに存在しています。 なし
ItemNotFound 要求されたリソースは存在しません。 なし
MemoryLimitReached メモリ制限に達しました。 アクションを完了できませんでした。 なし
NotImplemented 要求された機能は実装されていません。 つまり、API がプレビュー段階であるか、特定のプラットフォーム (オンライン専用など) でのみサポートされる可能性があります。 詳細については、「 Office アドインの Office クライアント アプリケーションとプラットフォームの可用性 」を参照してください。
RequestAborted 実行時に要求が中止されました。 なし
RequestPayloadSizeLimitExceeded 要求ペイロード サイズが制限を超えました。 詳細については、 Office アドインのリソース制限とパフォーマンス最適化 の記事を参照してください。 このエラーは、Office on the web でのみ発生します。
ResponsePayloadSizeLimitExceeded 応答のペイロード サイズが制限を超えました。 詳細については、 Office アドインのリソース制限とパフォーマンス最適化 の記事を参照してください。 このエラーは、Office on the web でのみ発生します。
ServiceNotAvailable サービスを利用できません。 なし
Unauthenticated 必要な認証情報が見つからないか、無効です。 なし
UnsupportedFeature ソース ワークシートにサポートされていない機能が 1 つ以上含まれているため、操作に失敗しました。 なし
UnsupportedOperation 試行中の操作はサポートされていません。 なし

Excel 固有のエラー コードとメッセージ

エラー コード エラー メッセージ 備考
EmptyChartSeries グラフ シリーズが空のため、試行された操作は失敗しました。 なし
FilteredRangeConflict 試行された操作により、フィルター処理された範囲との競合が発生します。 なし
FormulaLengthExceedsLimit 適用された式のバイトコードが最大長制限を超えています。 32 ビット コンピューター上の Office の場合、バイトコードの長さの制限は 16384 文字です。 64 ビット マシンでは、バイトコードの長さの制限は 32768 文字です。 このエラーは、Excel on the web とデスクトップの両方で発生します。
GeneralException 各種。 データ型 API は、動的なエラー メッセージで GeneralException エラーを返します。 これらのメッセージは、エラーのソースであるセルと、エラーの原因となっている問題を参照します ("セル A1 に必須プロパティ type がありません。"
InactiveWorkbook 複数のブックが開かれており、この API によって呼び出されているブックがフォーカスを失ったため、操作に失敗しました。 なし
InvalidOperationInCellEditMode Excel が [セルの編集] モードの間、この操作は使用できません。 Enter キーまたは Tab キーを使用するか、別のセルを選択して編集モードを終了し、もう一度試します。 なし
MergedRangeConflict 操作を完了できません。 1 つのテーブルを別のテーブル、ピボットテーブル レポート、クエリ結果、結合されたセル、または XML マップと重ねることはできません。 なし
NonBlankCellOffSheet Microsoft Excel では、空ではないセルがワークシートの末尾から押し出されるため、新しいセルを挿入できません。 これらの空ではないセルは空に見える場合がありますが、空白の値、いくつかの書式、または数式が含まれています。 挿入する内容を入れるのに十分な行または列を削除してから、もう一度やり直してください。 なし
OperationCellsExceedLimit 試行された操作は、33554000 セルの制限を超えて影響します。 TableColumnCollection.add APIがこのエラーをトリガーした場合は、ワークシート内でテーブル外に意図しないデータがないことを確認してください。 特に、ワークシートの右端の列のデータチェックを行います。 このエラーを解決するには、意図しないデータを削除します。 操作で処理されるセルの数を確認する方法の 1 つは、次の計算を実行することです。 (number of table rows) x (16383 - (number of table columns))。 数値 16383 は、Excel がサポートする列の最大数です。

このエラーは、Excel on the web でのみ発生します。
PivotTableRangeConflict 試行された操作により、ピボットテーブルの範囲との競合が発生します。 なし
RangeExceedsLimit 範囲内のセル数が、サポートされている最大数を超えています。 詳細については、 Office アドインのリソース制限とパフォーマンス最適化 の記事を参照してください。 なし
RefreshWorkbookLinksBlocked 外部ブック リンクを更新するためのアクセス許可がユーザーに付与されていないため、操作に失敗しました。 なし
UndoNotSupported JavaScript API 要求は、元に戻す操作がサポートされていないため失敗しました。 なし
UnsupportedSheet このシートの種類はマクロまたはグラフ シートであるため、この操作はサポートされていません。 なし

Word 固有のエラー コードとメッセージ

エラー コード エラー メッセージ 備考
SearchDialogIsOpen 検索ダイアログが開きます。 なし
SearchStringInvalidOrTooLong 検索文字列が無効であるか、長すぎます。 検索文字列の最大数は 255 文字です。

エラー通知

ユーザーにエラーを報告する方法は、使用している UI システムによって異なります。

  • UI システムとして React を使用している場合は、Fluent UI コンポーネントとデザイン要素を使用します。 エラー メッセージは ダイアログ コンポーネントで伝達することをお勧めします。 エラーがユーザーの入力にある場合は、エラーを太字の赤いテキストで表示するように 入力 コンポーネントを構成します。

    注:

    警告コンポーネントは、ユーザーにエラーを報告するためにも使用できますが、現在プレビュー段階であるため、運用アドインでは使用しないでください。 リリースステータスについては、Fluent UI React v9 コンポーネントロードマップを参照してください。

  • UI に React を使用していない場合は、HTML と JavaScript で直接実装された古い Fabric UI コンポーネントを使用することを検討してください。

関連項目

  • 最終更新: