Vorherige

Nächste

Arbeiten mit Dialogfeldern

Abgeschlossen

In dieser Lektion erfahren Sie, wie Sie Dialogfelder in Excel-Arbeitsmappen integrieren. Sie erfahren, wie Sie Dialoge eröffnen und wie Sie Eingaben und Ausgaben für den Dialog übermitteln und abrufen.

Dialoge

Die Dialog-API ist eine Erweiterung der Benutzererfahrung, die von Entwicklern in Office angepasst werden kann. Entwickler können diese verwenden, um Dialoge ausgehend von benutzerdefinierten Add-Ins, die mit dem Benutzer und mit der Benutzeroberfläche des benutzerdefinierten Add-Ins interagieren, zu eröffnen.

Das primäre Szenario für die Dialog-API ist die Authentifizierung bei Drittanbietern. Die meisten Identitätsanbieter verhindern, dass ihre Anmeldeerfahrungen aufgrund von Click-Jacking-Bedenken in einem <iframe> angezeigt werden. Dies ist mit einem Add-In problematisch, da sie in <iframe>einigen Clients angezeigt werden, z. B. in den Webversionen von Office-Clientanwendungen.

Eine weitere Herausforderung im Rahmen der Authentifizierungsszenarien ist die Vorhersage der Domänen, die geladen werden müssen. In Verbund-Anmeldeszenarien könnte die potenzielle Liste der Domänen endlos sein, was wiederum in einem Add-In, in dem alle Domänen im Manifest registriert werden müssen, problematisch ist.

Bitte unbedingt beachten, dass Office für Microsoft-Identitäten eine Benutzeroberfläche für einmaliges Anmelden (Single Sing-On) bietet. Wenn Ihr Add-In Daten über den Office-Benutzer oder deren Ressourcen erfordert, auf die über Microsoft Graph zugegriffen werden kann, z. B. Microsoft 365 oder OneDrive, empfiehlt Microsoft, wann immer möglich, die API für einmaliges Anmelden zu verwenden. Wenn Sie die APIs für einmaliges Anmelden verwenden, benötigen Sie die Dialog-API nicht.

Abgesehen von der Authentifizierung, kann die Dialog-API mehr Bildschirmplatz für Elemente bereitstellen, die sich in einem herkömmlichen Aufgabenbereich des Inhalts-Add-Ins nur schwer anzeigen lassen. Ein gutes Beispiel wäre, wenn Sie ein Video hosten wollten, das – wäre es auf einen Aufgabenbereich beschränkt – zu klein wäre.

Die Dialog-API kann eine beliebige HTTPS-Webseite anzeigen, allerdings muss sie zuerst in einer App-Domäne gestartet und dann umgeleitet werden.

Dialoge eröffnen

Öffnen Sie ein Dialogfeld mithilfe der displayDialogAsync()-Methode aus einem Office-Add-In:

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

Die displayDialogAsync()-Methode akzeptiert drei Parameter:

• Die <URL /> ist diejenige Seite, die im Dialogfeld angezeigt wird. Meist handelt sich dabei anfangs um eine Seite, die von einer App-Domäne aus gehostet wird, die im Manifest definiert ist. Allerdings kann die Seite direkt auf eine andere Seite umleiten.

• Der Parameter „options“ ermöglicht es dem Entwickler, die Größe des Dialogfelds zu ändern. Standardmäßig umfasst die Anzeige des Dialogfelds 80 % der Höhe und Breite des Gerätebildschirms. Die Werte für Höhe und Breite werden als Prozentsatz des Gerätebildschirms angegeben.

  Entwickler können optional die displayInIframe-Eigenschaft in den Optionen festlegen. Wenn diese Einstellung auf true festgelegt ist, wird das Dialogfeld als schwebendes IFRAME statt als unabhängiges Fenster (in Clients, das dies unterstützt) angezeigt, wodurch es schneller geöffnet wird.

• Der optionalCallback ermöglicht der Hostseite des Add-Ins das Reagieren auf Nachrichten und Ereignisse aus dem Dialogfeld.

Dialogfeld – Eingabe und Ausgabe

Primär erfolgt die Weitergabe von Informationen an ein Dialogfeld über den lokalen Speicher des Browsers (window.localStorage) oder über die URL-Parameter in der URL des Dialogs. In diesem Beispiel leitet die Hostseite über einen URL-Parameter die ID „123“ an den Dialog weiter.

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

Ein Dialog kann Messages an den Host zurückleiten, indem Office.context.ui.messageParentaufgerufen wird, um entweder einen booleschen Wert oder eine Zeichenfolgennachricht an die Hostseite zu senden. Am unteren Rand des Beispiels sehen Sie das Dialogskript, in dem die Meldung "Hello from the dialog!!" an das übergeordnete Element übergeben wird.

Die messageParent()-Methode kann nur auf einer Seite mit derselben Domäne (einschließlich Protokoll und Port) wie die Hostseite aufgerufen werden.

Die Hostseite muss nach Nachrichten „Ausschau halten“, indem Sie den DialogMessageReceived-Handler abonniert. Im Beispiel registriert die Hostseite diesen Handler mithilfe der processMessage()-Funktion, wobei die Nachricht in der-Konsole protokolliert wird.

Zusammenfassung

In dieser Lektion haben Sie erfahren, wie Dialoge in Excel-Arbeitsmappen integriert werden können. Sie haben außerdem erfahren, wie Sie Dialoge eröffnen und wie Sie Eingaben und Ausgaben für den Dialog übermitteln und abrufen können.

Weiter