Freigeben über

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

  • Artikel

Dieser Artikel enthält Regeln, Informationen 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).

Hinweis

Informationen zu den Grundlagen der Verwendung der Office-Dialog-API finden Sie unter Verwenden der Office-Dialogfeld-API in Ihren Office-Add-Ins.

Siehe auch Behandeln von Fehlern und Ereignissen mit dem Office-Dialogfeld.

Regeln und Tricks

  • Das Dialogfeld kann nur zu HTTPS-URLs und nicht zu HTTP navigieren.

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

  • Auf einer Hostseite kann jeweils nur ein Dialogfeld geöffnet sein. Die Hostseite kann entweder ein Aufgabenbereich oder die Funktionsdatei eines Funktionsbefehls sein.

  • Im Dialogfeld können nur zwei Office-APIs aufgerufen werden:

  • Die messageParent-Funktion sollte normalerweise von einer Seite aus aufgerufen werden, die sich genau in derselben Domäne wie das Add-In selbst befindet, aber dies ist nicht obligatorisch. Weitere Informationen finden Sie unter Domänenübergreifendes Senden von Nachrichten an die Hostlaufzeit.

    Tipp

    Wenn sich die Domäne Ihres Dialogfelds in Office im Web und in Outlook unter Windows von der Ihres Add-Ins unterscheidet und der Antwortheader Cross-Origin-Opener-Policy: same-origin erzwingt, wird Ihr Add-In für den Zugriff auf Nachrichten aus dem Dialogfeld blockiert, und Ihren Benutzern wird der Fehler 12006 angezeigt. Um dies zu verhindern, müssen Sie den Header auf Cross-Origin-Opener-Policy: unsafe-none festlegen oder Ihr Add-In und Dialogfeld so konfigurieren, dass sie sich in derselben Domäne befinden.

Bewährte Methoden

Vermeiden einer übermäßigen Verwendung 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. Ein Beispiel für einen Aufgabenbereich im Registerkartenformat finden Sie im Excel-Add-In JavaScript SalesTracker-Beispiel .

Entwerfen einer Dialogfeld-Benutzeroberfläche

Bewährte Methoden beim Entwerfen von Dialogfeldern finden Sie unter Dialogfelder in Office-Add-Ins.

Behandeln von Popupblockern mit Office im Web

Der Versuch, ein Dialogfeld anzuzeigen, während Office im Web verwendet wird, kann dazu führen, dass der Popupblocker des Browsers das Dialogfeld blockiert. Um dies zu verhindern, fordert Office im Web den Benutzer zum Öffnen des Dialogfelds Zulassen oder Ignorieren auf.

Die Eingabeaufforderung mit einer kurzen Beschreibung und den Schaltflächen Zulassen und Ignorieren, die ein Add-In generieren kann, um Popupblocker im Browser zu vermeiden.

Wenn der Benutzer Zulassen auswäht, wird das Dialogfeld Office geöffnet. Wenn der Benutzer Ignorieren auswäht, wird die Eingabeaufforderung geschlossen, und das Dialogfeld Office wird nicht geöffnet. Stattdessen gibt die Methode den displayDialogAsync Fehler 12009 zurück. Ihr Code sollte diesen Fehler abfangen und entweder eine alternative Benutzeroberfläche bereitstellen, die keinen Dialog erfordert, oder dem Benutzer eine Meldung anzeigen, die darauf hinweist, dass das Add-In den Dialog zulassen muss. (Weitere Informationen zu 12009 finden Sie unter Fehler von displayDialogAsync.)

Wenn Sie dieses Feature aus irgendeinem Grund deaktivieren möchten, muss Ihr Code deaktiviert werden. Diese Anforderung wird mit dem DialogOptions-Objekt ausgeführt, das an die displayDialogAsync -Methode übergeben wird. Insbesondere sollte das -Objekt enthalten promptBeforeOpen: false. Wenn diese Option auf false festgelegt ist, 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.

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 erfordert, ist ein Dialogfeld zum Anfordern von Berechtigungen über die Geräteberechtigungs-API verfügbar. Zu den Gerätefunktionen gehören kamera, geolocation und mikrofon eines Benutzers. Dies gilt für die folgenden Office-Anwendungen.

  • Office im Web (Excel, Outlook, PowerPoint und Word) wird in Chromium-basierten Browsern wie Microsoft Edge oder Google Chrome ausgeführt
  • neues 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.

Hinweis

  • Add-Ins, die auf Office-Desktopclients oder in Browsern ausgeführt werden, die nicht auf Chromium basieren, zeigen automatisch ein Dialogfeld an, in dem die Berechtigung eines Benutzers angefordert wird. Der Entwickler muss die Geräteberechtigungs-API auf diesen Plattformen nicht implementieren.
  • Add-Ins, die in Safari ausgeführt werden, können nicht auf die Gerätefunktionen eines Benutzers zugreifen. Die Geräteberechtigungs-API wird in Safari nicht unterstützt.

Verwenden Sie nicht den _host_info Wert.

Office fügt der URL, die an übergeben wird, automatisch einen Abfrageparameter mit dem Namen _host_info hinzu displayDialogAsync. Sie wird ggf. nach Ihren benutzerdefinierten Abfrageparametern angefügt. Es 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. Der gleiche Wert wird dem Sitzungsspeicher des Dialogfelds hinzugefügt (d. h. der Window.sessionStorage-Eigenschaft ). Auch hier sollte Ihr Code diesen Wert weder lesen noch schreiben.

Öffnen Eines weiteren Dialogfelds unmittelbar nach dem Schließen eines Dialogfelds

Sie können nicht mehr als ein Dialogfeld auf einer bestimmten Hostseite öffnen. Daher sollte Ihr Code Dialog.close in einem geöffneten Dialog aufrufen, bevor er aufruft displayDialogAsync , um einen anderen Dialog zu öffnen. Die close -Methode ist asynchron. Wenn Sie daher unmittelbar nach einem Aufruf von closeaufrufendisplayDialogAsync, ist der erste Dialog möglicherweise nicht vollständig geschlossen, wenn Office versucht, den zweiten zu öffnen. In diesem Fall gibt Office den Fehler 12007 zurück: "Fehler beim Vorgang, weil 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 es nicht mit dem await Schlüsselwort oder mit einer then Methode erwartet werden kann. Aus diesem Grund empfehlen wir das folgende Verfahren, wenn Sie unmittelbar nach dem Schließen eines Dialogs einen neuen Dialog ö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 aufruft, wenn der Aufruf von displayDialogAsync zurückgibt 12007. Es folgt ein Beispiel.

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 erzwingen, dass der Code angehalten wird, bevor er versucht, das zweite Dialogfeld mithilfe der setTimeout-Methode zu öffnen. Es folgt ein Beispiel.

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 single-page applications (SPAs) in der Regel, haben Sie die Möglichkeit, die URL einer Route an die displayDialogAsync-Methode anstelle der URL einer separaten HTML-Seite zu übergeben. Aus den unten angegebenen Gründen wird davon abgeraten.

Hinweis

Dieser Artikel ist nicht relevant für serverseitiges Routing, z. B. in einer Express-basierten Webanwendung.

Probleme mit SPAs und der Office-Dialog-API

Das Office-Dialogfeld befindet sich in einem neuen Fenster mit einer eigenen Instanz der JavaScript-Engine und ist daher ein eigener vollständiger 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 Instanz Ihrer Anwendung im Boxfenster herunter und startet sie, was den Zweck einer SPA teilweise verfehlt. Darüber hinaus ändert Code, der Variablen im Dialogfeldfenster ändert, nicht die Aufgabenbereichversion der gleichen Variablen. Ebenso verfügt das Dialogfeldfenster über einen eigenen Sitzungsspeicher (die Window.sessionStorage-Eigenschaft ), auf den über Code im Aufgabenbereich nicht zugegriffen werden kann. Das Dialogfeld und die Hostseite, auf der aufgerufen wurde, displayDialogAsync sehen wie zwei verschiedene Clients für Ihren Server aus. (Eine Erinnerung an eine Hostseite finden Sie unter Öffnen eines Dialogfelds von einer Hostseite.)

Wenn Sie also eine Route an die displayDialogAsync -Methode übergeben würden, verfügen Sie nicht wirklich über eine SPA. Sie verfügen über zwei Instanzen derselben SPA. Darüber hinaus würde ein Großteil des Codes in der Aufgabenbereichinstanz in dieser Instanz niemals verwendet, und ein Großteil des Codes in der Dialogfeldinstanz würde in dieser Instanz nie verwendet werden. Es wäre, als hätten Sie zwei SPAs im selben Bündel.

Microsoft Empfehlungen

Anstatt eine clientseitige Route an die displayDialogAsync -Methode zu übergeben, empfiehlt es sich, eine der folgenden Aktionen auszuführen:

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