前へ

次へ

ダイアログを操作する

完了

このユニットでは、Excel ブックにダイアログを組み込む方法について説明します。 ダイアログを開き、ダイアログの入力と出力を送信および取得する方法について説明します。

ダイアログ

ダイアログ API は、開発者が Office でカスタマイズできるユーザー エクスペリエンスの拡張機能です。 開発者はこれを使用して、ユーザーおよびカスタム アドインのユーザー エクスペリエンスと対話するカスタム アドインからダイアログを開くことができます。

ダイアログ API の主なシナリオは、サードパーティ プロバイダーの認証です。 ほとんどの ID プロバイダーは、クリックジャッキングの懸念があるため、サインイン エクスペリエンスが に <iframe> 表示されないようにします。 これは、Web バージョンの Office クライアント アプリケーションなどの一部のクライアントに表示されるため <iframe>、アドインでは面倒です。

認証シナリオの別な課題は、読み込む必要があるドメインを予測することです。 フェデレーション サインインのシナリオでは、潜在的なドメインのリストが無限になる可能性があります。これは、マニフェストにすべてのドメインを登録する必要があるアドインでは問題になります。

Office では、Microsoft ID 専用のシングル サインオン エクスペリエンスが提供されています。 アドインに、Office ユーザーのデータや、Microsoft 365 や OneDrive などの Microsoft Graph を使用してアクセスできるリソースのデータが必要な場合は、可能な限り、シングル サインオン API を使用することをお勧めします。 シングル サインオン用の API を使用する場合、ダイアログ API を使用する必要はありません。

認証以外にも、ダイアログ API を使用すると画面領域が追加され、コンテンツ アドインの従来の作業ウィンドウでは表示が困難だった要素を表示することができます。 良い例は、作業ウィンドウ内で再生すると小さすぎるビデオをホストする場合です。

ダイアログ API は、任意の HTTPS Web ページを表示できますが、まずアプリ ドメインに対して起動してから、リダイレクトする必要があります。

ダイアログを開く

Office アドインから displayDialogAsync() メソッドを使用してダイアログを開きます。

Office.context.ui.displayDialogAsync("<URL />", options, optionalCallback);

displayDialogAsync() メソッドは 3 つのパラメーターを受け取ります。

• <URL /> は、ダイアログに表示されるページです。 最初は、マニフェストの定義に従って、アプリ ドメインからホストされるページが表示されます。 ただし、このページは別のページにすぐにリダイレクトできます。

• 開発者は、options パラメーターを使用してダイアログのサイズを変更できます。 既定では、ダイアログはデバイス画面の高さと幅の 80% として表示されます。 高さと幅の値は、デバイス画面の割合として表されます。

  開発者は、必要に応じて、オプションの displayInIframe プロパティを設定できます。 これを true に設定すると、ダイアログはこれをサポートするクライアント内に独立したウィンドウとして表示されるのではなく、浮動 Iframe として表示されるので、より速く開きます。

• optionalCallback を使用すると、アドインのホスト ページで、ダイアログのメッセージやイベントに応答できます。

ダイアログの入力と出力

ダイアログに情報を渡す主な方法として、ブラウザーのローカル ストレージ (window.localStorage) を使用する方法と、ダイアログ URL の URL パラメーターを使用する方法があります。 このサンプルでは、ホスト ページは、URL パラメーターを使用して、ダイアログに 123 という ID を渡しています。

/******* START Host page script *******/

// Open the dialog passing the parameter id=123
let dialog = null;
Office.context.ui.displayDialogAsync(
  'https://domain/popup.html?id=123',
  {
    height: 45,
    width: 55
  },
  function(result) {
    dialog = result.value;
    // Listen for messages coming from the dialog
    dialog.addEventHandler(
      Microsoft.Office.WebExtension.EventType.DialogMessageReceived,
      processMessage
    );
  }
);
function processMessage(arg) {
  // Log the message send from the dialog and close the dialog
  console.log(arg.message);
  dialog.close();
}
/******* End Host page script *******/

/******* Start Dialog page script *******/
// dialog must call Office.initialize
Office.initialize = function() {
  // send the parent/host a message
  Office.context.ui.messageParent('Hello from the dialog!!!');
}

ダイアログは、ブール値または文字列メッセージのいずれかをホスト ページに送信する Office.context.ui.messageParent を呼び出すことにより、ホストにメッセージを返すことができます。 サンプルの下部には、"ダイアログから hello!!" というメッセージが親に渡されているダイアログ スクリプトが表示されます。

messageParent() メソッドを呼び出せるのは、ホスト ページと同じドメイン (プロトコルとポートを含む) を持つページ上のみです。

ホスト ページは、DialogMessageReceived ハンドラーを購読してメッセージをリッスンする必要があります。 このサンプルでは、ホスト ページは、processMessage() 関数を使用してこのハンドラーを登録します。これにより、コンソールにメッセージが記録されます。

要約

このユニットでは、Excel ブックにダイアログを組み込む方法について学習しました。 また、ダイアログを開き、ダイアログの入力と出力を送信および取得する方法についても学習しました。

続行