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

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

ベスト プラクティス

コード サンプルとScript Lab スニペットでは、または Word.run のすべてのExcel.runPowerPoint.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: エラー メッセージの プロパティにはcode、{application} が OfficeExtension.ErrorCodes Excel、PowerPoint、または{application}.ErrorCodesWordを表す文字列が含まれています。 たとえば、エラー コード "InvalidReference" は、参照が指定された操作に対して有効でないことを示します。 エラー コードはローカライズされません。

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

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

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

次の表に、アプリケーション固有の API から返される可能性があるエラーを示します。

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

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

エラー通知

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

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

  注:

  アラート コンポーネントを使用してユーザーにエラーを報告することもできますが、現在プレビュー段階であり、運用環境のアドインでは使用しないでください。 リリースの状態については、「Fluent UI React v9 コンポーネント ロードマップ」を参照してください。

• UI にReactを使用していない場合は、HTML と JavaScript で直接実装されている古い Fabric UI コンポーネントの使用を検討してください。 テンプレートの例としては、 Office-Add-in-UX-Design-Patterns-Code リポジトリがあります。 ダイアログとナビゲーション のサブフォルダーを特に見てみましょう。 Excel-Add-in-SalesLeads のサンプルでは、メッセージ バナーを使用します。

関連項目

• OfficeExtension.Error オブジェクト
• Office の一般的な API エラー コード