Office.UI interface

指定したイベント型を使用して、オブジェクトにイベント ハンドラーを追加します。

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

パラメーター

戻り値

注釈

要件セット: DialogAPI 1.2

各イベント ハンドラー関数の名前が一意である限り、指定したイベントの種類に対して複数のイベント ハンドラーを追加できます。

指定したイベント型を使用して、オブジェクトにイベント ハンドラーを追加します。

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;

パラメーター

戻り値

注釈

要件セット: DialogAPI 1.2

各イベント ハンドラー関数の名前が一意である限り、指定したイベントの種類に対して複数のイベント ハンドラーを追加できます。

例

// The following example shows how to add an event handler for the DialogParentMessageReceived event.
Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onMessageFromParent(arg) {
    const messageFromParent = JSON.parse(arg.message);
    document.querySelector('h1').textContent = messageFromParent.name;
}

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }
}

JavaScript が実行されている UI コンテナーを閉じます。

closeContainer(): void;

戻り値

注釈

アプリケーション: Excel、Outlook (最小要件セット: メールボックス 1.5)、PowerPoint、Word

要件セット:

• DialogAPI

• Mailbox 1.5

このメソッドの動作は、次のように指定されます。

• UI なしのコマンド ボタンから呼び出される: 効果なし。 displayDialogAsync によって開かれたダイアログは開いたままになります。

• 作業ウィンドウから呼び出される: 作業ウィンドウが閉じます。 displayDialogAsync によって開かれたダイアログも閉じます。 作業ウィンドウがピン留めをサポートしていて、ユーザーによってピン留めされた場合、ピン留めされません。

• モジュール拡張機能から呼び出される: 効果なし。

例

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();

ユーザーから情報を表示または収集したり、Web ナビゲーションを容易にしたりするためのダイアログを表示します。

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;

パラメーター

戻り値

注釈

アプリケーション: Excel、Outlook、PowerPoint、Word

要件セット:

• DialogAPI

• Mailbox 1.4

このメソッドは、Excel、PowerPoint、または Word アドインの DialogApi 要件セットと、Outlook のメールボックス要件セット 1.4 で使用できます。 マニフェストで要件セットを指定する方法の詳細については、アドインのみのマニフェストを使用している場合は、「Office アプリケーションと API の要件を指定する」を参照してください。 Microsoft 365 の統合マニフェストを使用している場合は、「Office アドインと Microsoft 365 の統合アプリ マニフェスト」を参照してください。

最初のページは、親ページ (startAddress パラメーター) と同じドメイン上にある必要があります。 初期ページが読み込まれた後、他のドメインに移動できます。

Office.context.ui.messageParentを呼び出すページは、親ページと同じドメインにも存在する必要があります。

設計に関する考慮事項:

ダイアログ ボックスには、次の設計上の考慮事項が適用されます。

• Office アドイン作業ウィンドウで開くことができるダイアログ ボックスは、いつでも 1 つだけです。 アドイン コマンド (カスタム リボン ボタンまたはメニュー項目) から複数のダイアログを同時に開くことができます。

• ユーザーは、すべてのダイアログ ボックスを移動およびサイズ変更できます。

• すべてのダイアログ ボックスは、画面の中央に開かれます。

• ダイアログ ボックスは、アプリケーションの上部と、ダイアログ ボックスが作成された順序で表示されます。

ダイアログ ボックスは次のような場合に使用します。

• ユーザーの資格情報を収集する認証ページを表示します。

• ShowTaskpane または ExecuteAction コマンドからエラー/進行状況/入力画面を表示します。

• ユーザーがタスクの完了に利用できる表示領域を一時的に拡大します。

ドキュメントとの対話にはダイアログ ボックスを使用しないでください。 代わりに作業ウィンドウを使用してください。

displayDialogAsync エラー

displayDialogAsync メソッドに渡されるコールバック関数では、AsyncResult オブジェクトのプロパティを使用して、次の情報を返すことができます。

例

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog. The implementation of the processMessage() function is omitted.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        const dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

// The following example does the same thing in TypeScript.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult: Office.AsyncResult) => {
        const dialog: Office.Dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

ユーザーから情報を表示または収集したり、Web ナビゲーションを容易にしたりするためのダイアログを表示します。

displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): void;

パラメーター

戻り値

注釈

アプリケーション: Excel、Outlook、PowerPoint、Word

要件セット:

• DialogAPI

• Mailbox 1.4

このメソッドは、Excel、PowerPoint、または Word アドインの DialogApi 要件セットと、Outlook のメールボックス要件セット 1.4 で使用できます。 マニフェストで要件セットを指定する方法の詳細については、アドインのみのマニフェストを使用している場合は、「Office アプリケーションと API の要件を指定する」を参照してください。 Microsoft 365 の統合マニフェストを使用している場合は、「Office アドインと Microsoft 365 の統合アプリ マニフェスト」を参照してください。

最初のページは、親ページ (startAddress パラメーター) と同じドメイン上にある必要があります。 初期ページが読み込まれた後、他のドメインに移動できます。

Office.context.ui.messageParentを呼び出すページは、親ページと同じドメインにも存在する必要があります。

設計に関する考慮事項:

ダイアログ ボックスには、次の設計上の考慮事項が適用されます。

• Office アドイン作業ウィンドウで開くことができるダイアログ ボックスは、いつでも 1 つだけです。 アドイン コマンド (カスタム リボン ボタンまたはメニュー項目) から複数のダイアログを同時に開くことができます。

• ユーザーは、すべてのダイアログ ボックスを移動およびサイズ変更できます。

• すべてのダイアログ ボックスは、画面の中央に開かれます。

• ダイアログ ボックスは、アプリケーションの上部と、ダイアログ ボックスが作成された順序で表示されます。

ダイアログ ボックスは次のような場合に使用します。

• ユーザーの資格情報を収集する認証ページを表示します。

• ShowTaskpane または ExecuteAction コマンドからエラー/進行状況/入力画面を表示します。

• ユーザーがタスクの完了に利用できる表示領域を一時的に拡大します。

ドキュメントとの対話にはダイアログ ボックスを使用しないでください。 代わりに作業ウィンドウを使用してください。

displayDialogAsync エラー

displayDialogAsync メソッドに渡されるコールバック関数では、AsyncResult オブジェクトのプロパティを使用して、次の情報を返すことができます。

メッセージをダイアログ ボックスからその親/オープナー ページに配信します。

messageParent(message: string, messageOptions?: DialogMessageOptions): void;

パラメーター

戻り値

注釈

要件セット:

• DialogAPI

• messageOptions パラメーターを使用する場合は、DialogOrigin 1.1 も必要です。

例

// The following example shows how to send a JSON string to the parent. The profile object
// is returned from some website when a user signs into it.
function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

ブラウザー ウィンドウを開き、指定した URL を読み込みます。

openBrowserWindow(url: string): void;

パラメーター

戻り値

注釈

要件セット: OpenBrowserWindowAPI 1.1

例

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();