Office.UI interface

Office アドインで、ダイアログ ボックスなどの UI コンポーネントを作成および操作するために使用できるオブジェクトとメソッドを提供します。

詳細については、「Office アドインでダイアログ API を使用する」を参照してください。

メソッド

addHandlerAsync(eventType, handler, options, callback)

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

addHandlerAsync(eventType, handler, callback)

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

closeContainer()

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

displayDialogAsync(startAddress, options, callback)

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

displayDialogAsync(startAddress, callback)

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

messageParent(message, messageOptions)

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

openBrowserWindow(url)

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

メソッドの詳細

addHandlerAsync(eventType, handler, options, callback)

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

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

パラメーター

eventType
Office.EventType

追加するイベントの種類を指定します。 これは である Office.EventType.DialogParentMessageReceived必要があります。

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

追加するイベント ハンドラー関数。パラメーターは Office.DialogParentMessageReceivedEventArgs 型のみです。

options
Office.AsyncContextOptions

コールバックで使用するために、任意の型のコンテキスト データを変更せずに保持するためのオプションを提供します。

callback

(result: Office.AsyncResult<void>) => void

省略可能です。 ハンドラー登録が返されるときに呼び出される関数。パラメーターは Office.AsyncResult 型のみです。

戻り値

void

注釈

要件セット: DialogAPI 1.2

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

addHandlerAsync(eventType, handler, callback)

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

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

パラメーター

eventType
Office.EventType

追加するイベントの種類を指定します。 これは である Office.EventType.DialogParentMessageReceived必要があります。

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

追加するイベント ハンドラー関数。パラメーターは Office.DialogParentMessageReceivedEventArgs 型のみです。

callback

(result: Office.AsyncResult<void>) => void

省略可能です。 ハンドラー登録が返されるときに呼び出される関数。パラメーターは Office.AsyncResult 型のみです。

戻り値

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;
    }
}

closeContainer()

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

closeContainer(): void;

戻り値

void

注釈

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

要件セット:

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

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

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

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

displayDialogAsync(startAddress, options, callback)

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

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

パラメーター

startAddress

string

ダイアログで開く最初の完全な HTTPS URL を受け入れます。 相対 URL は使用しないでください。

options
Office.DialogOptions

省略可能です。 ダイアログ表示を定義するために Office.DialogOptions オブジェクトを受け入れます。

callback

(result: Office.AsyncResult<Office.Dialog>) => void

オプション。 ダイアログの作成試行を処理するコールバック関数を受け入れます。 成功した場合、AsyncResult.value は Dialog オブジェクトです。

戻り値

void

注釈

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

要件セット:

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

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

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

設計に関する考慮事項:

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

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

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

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

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

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

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

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

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

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

displayDialogAsync エラー

コード番号 意味
12004 displayDialogAsync に渡される URL のドメインは信頼されていません。 ドメインは、ホスト ページと同じドメイン (プロトコルとポート番号を含む) にするか、またはアドイン マニフェストの AppDomains セクションで登録する必要があります。
12005 displayDialogAsync に渡される URL は HTTP プロトコルを使用します。 HTTPS が必要です。 (Office の一部のバージョンでは、12004 で返されるのと同じエラー メッセージが、12005 でも返されます)。
12007 ダイアログ ボックスは、作業ウィンドウで既に開いています。 作業ウィンドウ アドインで一度に開けるダイアログ ボックスは 1 つだけです。
12009 ダイアログ ボックスを無視するようにユーザーが選択しました。 このエラーは、ダイアログの表示をアドインに許可しないようにユーザーが選択すると、Office のオンライン バージョンで発生することがあります。

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

プロパティ 使用
AsyncResult.value Dialog オブジェクトにアクセスする
AsyncResult.status 操作の成功または失敗を判断する
AsyncResult.error 操作が失敗した場合にエラー情報を提供する Error オブジェクトにアクセスする
AsyncResult.asyncContext asyncContext パラメーターとして渡した場合は、ユーザー定義のオブジェクトまたは値にアクセスします

// 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);
        });
    }
);

displayDialogAsync(startAddress, callback)

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

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

パラメーター

startAddress

string

ダイアログで開く最初の完全な HTTPS URL を受け入れます。 相対 URL は使用しないでください。

callback

(result: Office.AsyncResult<Office.Dialog>) => void

省略可能です。 ダイアログの作成試行を処理するコールバック関数を受け入れます。 成功した場合、AsyncResult.value は Dialog オブジェクトです。

戻り値

void

注釈

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

要件セット:

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

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

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

設計に関する考慮事項:

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

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

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

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

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

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

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

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

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

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

displayDialogAsync エラー

コード番号 意味
12004 displayDialogAsync に渡される URL のドメインは信頼されていません。 ドメインは、ホスト ページと同じドメイン (プロトコルとポート番号を含む) にするか、またはアドイン マニフェストの AppDomains セクションで登録する必要があります。
12005 displayDialogAsync に渡される URL は HTTP プロトコルを使用します。 HTTPS が必要です。 (Office の一部のバージョンでは、12004 で返されるのと同じエラー メッセージが、12005 でも返されます)。
12007 ダイアログ ボックスは、作業ウィンドウで既に開いています。 作業ウィンドウ アドインで一度に開けるダイアログ ボックスは 1 つだけです。
12009 ダイアログ ボックスを無視するようにユーザーが選択しました。 このエラーは、ダイアログの表示をアドインに許可しないようにユーザーが選択すると、Office のオンライン バージョンで発生することがあります。

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

プロパティ 使用
AsyncResult.value Dialog オブジェクトにアクセスする
AsyncResult.status 操作の成功または失敗を判断する
AsyncResult.error 操作が失敗した場合にエラー情報を提供する Error オブジェクトにアクセスする
AsyncResult.asyncContext asyncContext パラメーターとして渡した場合は、ユーザー定義のオブジェクトまたは値にアクセスします

messageParent(message, messageOptions)

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

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

パラメーター

message

string

ダイアログからメッセージを受け付け、アドインに配信します。 JSON や XML を含む文字列にシリアル化できるものは、すべて送信できます。

messageOptions
Office.DialogMessageOptions

オプション。 メッセージを送信する方法のオプションを提供します。

戻り値

void

注釈

要件セット:

// 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));
}

openBrowserWindow(url)

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

openBrowserWindow(url: string): void;

パラメーター

url

string

プロトコル (https など) とポート番号 (存在する場合) を含む、開く完全な URL。

戻り値

void

注釈

要件セット: OpenBrowserWindowAPI 1.1