Bewährte Methoden und Regeln für die Office-Dialog-API

Dieser Artikel enthält Regeln, Einschränkungen und bewährte Methoden für die Office Dialog-API, einschließlich bewährter Methoden für das Entwerfen der Benutzeroberfläche eines Dialogfelds und die Verwendung der API in einer Single-Page-Anwendung (SPA).

Regeln und Beschränkungen

• In einem Dialogfeld kann nur zu HTTPS-URLs navigiert werden, nicht zu HTTP.

• Die URL, die Sie an die displayDialogAsync-Methode übergeben, muss sich in genau derselben Domäne wie das Add-In selbst befinden. Es darf keine Unterdomäne sein. Die Seite, die Sie an sie übergeben, kann jedoch zu einer Seite in einer anderen Domäne umleiten.

• Auf einer Hostseite kann jeweils nur ein Dialogfeld geöffnet sein. Die Hostseite kann entweder ein Aufgabenbereich oder die Funktionsdatei eines Funktionsbefehls sein. Sie können mehrere Dialogfelder gleichzeitig über benutzerdefinierte Menübandschaltflächen oder Menüelemente öffnen.

• Das Dialogfeld kann nur zwei Office-APIs aufrufen:

  • Office.context.ui.messageParent
  • Office.context.requirements.isSetSupported (Weitere Informationen finden Sie unter Angeben von Office-Anwendungen und API-Anforderungen.)

• Normalerweise rufen Sie die messageParent-Funktion von einer Seite aus auf, die sich in genau derselben Domäne wie das Add-In selbst befindet, aber dies ist nicht zwingend erforderlich. Weitere Informationen finden Sie unter Domänenübergreifendes Senden von Nachrichten an die Hostlaufzeit.

• Wenn ein Dialogfeld geöffnet wird, wird es auf dem Bildschirm über der Office-Anwendung zentriert.

• Der Benutzer kann ein Dialogfeld verschieben und dessen Größe ändern.

• Ein Dialogfeld wird in der Reihenfolge angezeigt, in der es erstellt wurde.

  Tipp

  Wenn sich die Domäne Ihres Dialogfelds in Office im Web und im neuen Outlook unter Windows von der Ihres Add-Ins unterscheidet und die Cross-Origin-Opener-Policy: Same-Origin Response-Header erzwungen wird, wird Ihr Add-In für den Zugriff auf Nachrichten aus dem Dialogfeld gesperrt, und Ihren Benutzern wird der Fehler 12006 angezeigt. Um diesen Fehler zu vermeiden, stellen Sie den Header auf Add-In und Dialogfeld so ein, dass Cross-Origin-Opener-Policy: unsafe-none sie sich in derselben Domäne befinden, oder konfigurieren Sie es.

• Legen Sie im Outlook im Web und im neuen Outlook unter Windows die Eigenschaft window.name nicht fest, wenn Sie ein Dialogfeld in Ihrem Add-In konfigurieren. Diese Outlook-Clients verwenden die window.name Eigenschaft, um die Funktionalität über Seitenumleitungen hinweg beizubehalten.

Bewährte Methoden

Vermeiden Sie den übermäßigen Gebrauch von Dialogfeldern

Da eine überlappende Benutzeroberfläche für Benutzer störend sein kann, sollten Dialogfelder nur dann aus einem Aufgabenbereich geöffnet werden, wenn dies für Ihr Szenario erforderlich ist. Bedenken Sie bei Ihren Überlegungen bezüglich der Verwendung des Oberflächenbereichs eines Aufgabenbereichs, dass Aufgabenbereiche in Registerkarten unterteilt werden können.

Entwerfen eines Dialogfelds Benutzeroberfläche

Bewährte Methoden für den Entwurf von Dialogfeldern finden Sie unter Dialogfelder in Office-Add-Ins.

Umgang mit Popupblockern mit Office im Web

Wenn Sie versuchen, während der Verwendung von Office im Web ein Dialogfeld anzuzeigen, blockiert der Popupblocker des Browsers das Dialogfeld möglicherweise. Um dieses Problem zu vermeiden, fordert Office im Web den Benutzer auf, das Öffnen des Dialogfelds zuzulassen oder zu ignorieren.

Wenn der Benutzer Zulassen auswählt, wird das Office-Dialogfeld geöffnet. Wenn der Benutzer "Ignorieren" wählt, wird die Eingabeaufforderung geschlossen, und das Office-Dialogfeld wird nicht geöffnet. Stattdessen gibt die displayDialogAsync Methode den Fehler 12009 zurück. Ihr Code sollte diesen Fehler abfangen und entweder eine alternative Oberfläche bereitstellen, die kein Dialogfeld erfordert, oder dem Benutzer eine Meldung anzeigen, in der er darauf hingewiesen wird, dass er das Dialogfeld für das Add-In zulassen muss. Weitere Informationen zu Fehler 12009 finden Sie unter Fehler von displayDialogAsync.

Umgang mit blockierten Dialogfeldern (Fehler 12009)

Ihr Add-In sollte den Fehler 12009 immer ordnungsgemäß behandeln. Hier sind einige empfohlene Ansätze:

• Zeigen Sie eine benutzerfreundliche Meldung an, die erklärt, warum das Dialogfeld erforderlich ist.

  Office.context.ui.displayDialogAsync(
    "https://www.contoso.com/auth.html",
    { height: 60, width: 30 },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        if (asyncResult.error.code === 12009) {
          // User blocked the dialog.
          showNotification(
            "Dialog Required",
            "This add-in needs to open a dialog to sign you in. " +
            "Please click the add-in button again and choose 'Allow' when prompted."
          );
        } else {
          // Handle other errors.
          showNotification("Error", `Unable to open dialog: ${asyncResult.error.message}`);
        }
      } else {
        // Dialog opened successfully.
        const dialog = asyncResult.value;
        // ... Handle dialog events here.
      }
    }
  );
  

• Stellen Sie nach Möglichkeit einen alternativen Workflow bereit. Wenn Ihr Add-In mit eingeschränkten Funktionen funktionieren kann, wenn das Dialogfeld blockiert ist, bieten Sie dem Benutzer diese Alternative an.

Deaktivieren der Eingabeaufforderung

Wenn Sie die Eingabeaufforderung zum Zulassen/Ignorieren deaktivieren möchten, muss Ihr Code deaktiviert werden. Stellen Sie diese Anforderung mithilfe des DialogOptions-Objekts , das Sie an die displayDialogAsync Methode übergeben. Genauer gesagt, in das Objekt einschließen promptBeforeOpen: false . Wenn Sie diese Option auf "false" festlegen, fordert Office im Web den Benutzer nicht auf, dem Add-In das Öffnen eines Dialogfelds zu erlauben, und das Office-Dialogfeld wird nicht geöffnet, wenn der Popupblocker des Browsers dies blockieren würde.

Anfordern des Zugriffs auf Gerätefunktionen in Office im Web und dem neuen Outlook unter Windows

Wenn Ihr Add-In Zugriff auf die Gerätefunktionen eines Benutzers benötigt, verwenden Sie die Geräteberechtigungs-API , um Berechtigungen über ein Dialogfeld anzufordern. Zu den Gerätefunktionen gehören die Kamera, die Geolokalisierung und das Mikrofon eines Benutzers. Diese Anforderung gilt für die folgenden Office-Anwendungen.

• Office im Web (Excel, Outlook, PowerPoint und Word), das in Chromium-basierten Browsern wie Microsoft Edge oder Google Chrome ausgeführt wird
• Das neue Outlook unter Windows

Wenn Ihr Add-In Office.context.devicePermission.requestPermissions oder Office.context.devicePermission.requestPermissionsAsync aufruft, wird ein Dialogfeld mit den angeforderten Gerätefunktionen und den Optionen "Zulassen", "Einmal zulassen" oder "Zugriff verweigern" angezeigt. Weitere Informationen finden Sie unter Anzeigen, Verwalten und Installieren von Add-Ins für Excel, PowerPoint und Word.

Verwenden Sie nicht den Wert _host_info

Office fügt der URL, die an displayDialogAsyncübergeben wird, automatisch einen Abfrageparameter namens _host_info hinzu. Dieser Parameter wird ggf. nach Ihren benutzerdefinierten Abfrageparametern angefügt. Dieser Parameter wird nicht an nachfolgende URLs angefügt, zu denen das Dialogfeld navigiert. Microsoft kann den Inhalt dieses Werts ändern oder vollständig entfernen, sodass Ihr Code ihn nicht lesen sollte. Derselbe Wert wird dem Sitzungsspeicher des Dialogfelds hinzugefügt (d. h. der Window.sessionStorage-Eigenschaft ). Auch hier sollte der Code diesen Wert weder lesen noch schreiben.

Öffnen eines weiteren Dialogfelds sofort nach dem Schließen eines Dialogfelds

Sie können nicht mehr als einen Dialog von einer bestimmten Hostseite aus geöffnet haben, daher sollte Ihr Code Dialog.close für einen geöffneten Dialog aufrufen, bevor er aufruft displayDialogAsync , um einen anderen Dialog zu öffnen. Die close Methode ist asynchron. Aus diesem Grund wird das erste Dialogfeld möglicherweise nicht vollständig geschlossen, wenn Office versucht, das zweite Dialogfeld zu öffnen, wenn Sie displayDialogAsync unmittelbar nach einem Aufruf von closeanrufen. In diesem Fall gibt Office einen 12007-Fehler zurück: "Fehler beim Vorgang, da dieses Add-In bereits über ein aktives Dialogfeld verfügt."

Die close Methode akzeptiert keinen Rückrufparameter und gibt kein Promise-Objekt zurück, sodass weder mit dem await Schlüsselwort (keyword) noch mit einer then Methode darauf gewartet werden kann. Verwenden Sie aus diesem Grund die folgende Technik, wenn Sie einen neuen Dialog sofort nach dem Schließen eines Dialogs öffnen müssen: kapseln Sie den Code, um den neuen Dialog in einer Funktion zu öffnen, und entwerfen Sie die Funktion so, dass sie sich rekursiv selbst aufruft, wenn der Aufruf von displayDialogAsync zurückkehrt 12007. Das folgende Beispiel zeigt, wie diese Technik implementiert wird.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/firstDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        openSecondDialog();
      }
      else {
         // Handle errors.
      }
    }
  );
}
 
function openSecondDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/secondDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        if (result.error.code === 12007) {
          openSecondDialog(); // Recursive call.
        }
        else {
         // Handle other errors.
        }
      }
    }
  );
}

Alternativ können Sie mit der "setTimeout "-Methode erzwingen, dass der Code angehalten wird, bevor er versucht, das zweite Dialogfeld zu öffnen. Das folgende Beispiel zeigt, wie Sie diesen Ansatz implementieren.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/firstDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        setTimeout(() => { 
          Office.context.ui.displayDialogAsync(
            "https://MyDomain/secondDialog.html",
            { width: 50, height: 50 },
            (result) => {
              // Callback body.
            }
          );
        }, 1000);
      }
      else {
         // Handle errors.
      }
    }
  );
}

Bewährte Methoden für die Verwendung der Office-Dialog-API in einer SPA

Wenn Ihr Add-In clientseitiges Routing verwendet, wie dies bei Single-Page-Anwendungen (SPAs) üblicherweise der Fall ist, können Sie die URL einer Route an die displayDialogAsync-Methode übergeben, anstatt die URL einer separaten HTML-Seite. Verwenden Sie diesen Ansatz aus den im folgenden Abschnitt genannten Gründen nicht.

Probleme mit SPAs und der Office-Dialog-API

Das Office-Dialogfeld befindet sich in einem neuen Fenster mit einer eigenen Instanz des JavaScript-Moduls und somit einem eigenen vollständigen Ausführungskontext. Wenn Sie eine Route übergeben, werden Ihre Basisseite und ihr gesamter Initialisierungs- und Bootstrappingcode in diesem neuen Kontext erneut ausgeführt, und alle Variablen werden im Dialogfeld auf ihre Anfangswerte festgelegt. Diese Technik lädt also eine zweite Instance Ihrer Anwendung im Dialogfenster herunter und startet sie, was den Zweck einer SPA teilweise zunichte macht. Darüber hinaus ändert Code, der Variablen im Dialogfeldfenster ändert, nicht die Aufgabenbereichsversion derselben Variablen. Ebenso verfügt das Dialogfeldfenster über einen eigenen Sitzungsspeicher (die Window.sessionStorage-Eigenschaft ), auf den nicht über Code im Aufgabenbereich zugegriffen werden kann. Das Dialogfeld und die Hostseite, auf der es aufgerufen wurde, displayDialogAsync sehen für Ihren Server wie zwei verschiedene Clients aus. (Eine Erinnerung daran, was eine Hostseite ist, finden Sie unter Öffnen eines Dialogfelds von einer Hostseite aus.)

Wenn Sie also eine Route an die displayDialogAsync Methode übergeben, haben Sie nicht wirklich eine SPA, sondern zwei Instanzen derselben SPA. Darüber hinaus wird ein Großteil des Codes in der Aufgabenbereich-Instance nie in dieser Instance verwendet, und ein Großteil des Codes in der Dialogfeld-instance wird nie in dieser instance verwendet. Es ist, als hätten Sie zwei SPAs im selben Paket.

Microsoft Empfehlungen

Anstatt eine clientseitige Route an die displayDialogAsync Methode zu übergeben, verwenden Sie einen der folgenden Ansätze.

• Wenn der Code, den Sie im Dialogfeld ausführen möchten, komplex genug ist, erstellen Sie explizit zwei verschiedene SPAs. das heißt, sie haben zwei SPAs in verschiedenen Ordnern derselben Domäne. Eine SPA wird im Dialogfeld und die andere auf der Hostseite des Dialogfelds ausgeführt, auf der displayDialogAsync sie aufgerufen wurde.
• In den meisten Szenarien ist nur einfache Logik im Dialogfeld erforderlich. In solchen Fällen wird Ihr Projekt erheblich vereinfacht, indem Sie eine einzige HTML-Seite mit eingebettetem oder referenziertem JavaScript in der Domäne Ihrer SPA hosten. Übergeben Sie die URL der Seite an die displayDialogAsync-Methode. Dieser Ansatz bedeutet zwar, dass Sie von der wörtlichen Idee einer Single-Page-App abweichen, aber Sie haben nicht wirklich eine einzige Instance einer SPA, wenn Sie die Office Dialog-API verwenden.

Siehe auch

• Verwenden der Office-Dialogfeld-API in Office-Add-Ins
• Behandeln von Fehlern und Ereignissen im Dialogfeld "Office"