次の方法で共有

[Office] ダイアログ ボックスでエラーとイベントを処理する

この記事では、ダイアログ ボックスを開くときにエラーをトラップして処理する方法と、ダイアログ ボックス内で発生するエラーについて説明します。

注:

この記事では、「Office アドインで Office ダイアログ API を使用する」の説明に従って、 Office ダイアログ API の使用の基本について理解していることを前提とします。

「Office ダイアログ API のベスト プラクティスとルール」も参照してください。

コードでは、2 つのカテゴリのイベントを処理する必要があります。

  • ダイアログ ボックスを作成できないため、 displayDialogAsync の呼び出しによって返されるエラー。
  • ダイアログ ボックスのエラー、およびその他のイベント。

displayDialogAsync のエラー

一般的なプラットフォーム エラーとシステム エラーに加えて、4 つのエラーは、 displayDialogAsyncの呼び出しに固有です。

コード番号 意味
12004 displayDialogAsyncに渡される URL のドメインは信頼されていません。 ドメインは、ホスト ページと同じドメインにある必要があります (プロトコルとポート番号を含む)。

Outlook on the webと新しい Outlook on Windows では、このエラーは、アドインが localhost サーバーでホストされていて、そのマニフェストで localhost に AppDomain 要素が指定されていない場合に発生します。
12005 displayDialogAsync に渡される URL には HTTP プロトコルを使用します。 HTTPS が必要です。 (一部のバージョンの Office では、12005 で返されるエラー メッセージ テキストは、12004 で返されたものと同じです)。
12007 ダイアログ ボックスは、このホスト ウィンドウで既に開いています。 作業ウィンドウなどのホスト ウィンドウで一度に開けるダイアログ ボックスは 1 つだけです。
12009 ダイアログ ボックスを無視するようにユーザーが選択しました。 このエラーは、ユーザーがアドインにダイアログ ボックスの表示を許可しないことを選択できるOffice on the webで発生する可能性があります。 詳細については、「Office on the webでのポップアップ ブロックの処理」を参照してください。
12011 アドインはOffice on the webで実行されており、ユーザーのブラウザー構成によってポップアップがブロックされています。 これは最も一般的に、ブラウザーが Edge レガシであり、アドインのドメインが、ダイアログを開こうとしているドメインとは異なるセキュリティ ゾーンにある場合に発生します。 このエラーをトリガーするもう 1 つのシナリオは、ブラウザーが Safari であり、すべてのポップアップをブロックするように構成されていることです。 ブラウザーの構成を変更するか、別のブラウザーを使用するようにユーザーにプロンプトを表示して、このエラーに対応することを検討してください。

displayDialogAsyncが呼び出されると、AsyncResult オブジェクトがそのコールバック関数に渡されます。 呼び出しが成功すると、ダイアログ ボックスが開き、AsyncResult オブジェクトのvalue プロパティが Dialog オブジェクトになります。 この例については、「 ダイアログ ボックスからホスト ページに情報を送信する」を参照してください。 displayDialogAsyncの呼び出しが失敗すると、ダイアログ ボックスは作成されません。AsyncResult オブジェクトの status プロパティは Office.AsyncResultStatus.Failed に設定され、オブジェクトのerror プロパティが設定されます。 statusをテストし、エラーが発生したときに応答するコールバックを常に提供する必要があります。 コード番号に関係なくエラー メッセージを報告する例については、次のコードを参照してください。 (この記事で定義されていない showNotification 関数は、エラーを表示またはログに記録します。アドイン内でこの関数を実装する方法の例については、「 Office アドイン ダイアログ API の例」を参照してください)。

let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        showNotification(asyncResult.error.code = ": " + asyncResult.error.message);
    } else {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
});

ダイアログ ボックスのエラーとイベント

ダイアログ ボックスの 3 つのエラーとイベントによって、ホスト ページで DialogEventReceived イベントが発生します。 ホスト ページの内容のリマインダーについては、「ホスト ページ からダイアログ ボックスを開く」を参照してください。

コード番号 意味
12002 以下のいずれか:
  • displayDialogAsyncに渡された URL にページが存在しません。
  • 読み込まれた displayDialogAsync に渡されたページが、ダイアログ ボックスが見つからないページまたは読み込みできないページにリダイレクトされたか、無効な構文を持つ URL にリダイレクトされました。
12003 ダイアログ ボックスが HTTP プロトコルを使用している URL を指していました。 HTTPS が必要です。
12006 以下のいずれか:
  • ダイアログ ボックスは閉じられました。通常、ユーザーが [閉じる ] ボタン X を選択したためです。
  • このダイアログでは、 クロスオリジン-Opener-Policy: same-origin 応答ヘッダーが返されました。 これを防ぐには、ヘッダーを Cross-Origin-Opener-Policy: unsafe-none に設定するか、ホスト ページと同じドメインにアドインとダイアログを構成する必要があります。

コードで、呼び出し内の DialogEventReceived イベントのハンドラーを displayDialogAsync に割り当てることができます。 次に簡単な例を示します。

let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
    function (result) {
        dialog = result.value;
        dialog.addEventHandler(Office.EventType.DialogEventReceived, processDialogEvent);
    }
);

エラー コードごとにカスタム エラー メッセージを作成する DialogEventReceived イベントのハンドラーの例については、次の例を参照してください。

function processDialogEvent(arg) {
    switch (arg.error) {
        case 12002:
            showNotification("The dialog box has been directed to a page that it can't find or load, or the URL syntax is invalid.");
            break;
        case 12003:
            showNotification("The dialog box has been directed to a URL with the HTTP protocol. HTTPS is required.");            break;
        case 12006:
            showNotification("Dialog closed.");
            break;
        default:
            showNotification("Unknown error in dialog box.");
            break;
    }
}

関連項目

この方法でエラーを処理するサンプル アドインについては、「Office アドイン ダイアログ API の例」を参照してください。