Verwenden der Office-Dialog-API in Office-Add-Ins

Verwenden Sie die Office-Dialogfeld-API , um Dialogfelder in Ihrem Office-Add-In zu öffnen. Dieser Artikel enthält eine Anleitung für die Verwendung der Dialog-API in Ihrem Office-Add-In. Erwägen Sie, ein Dialogfeld über einen Aufgabenbereich, ein Inhalts-Add-In oder einen Add-In-Befehl zu öffnen, um die folgenden Aufgaben auszuführen.

• Melden Sie einen Benutzer mit einer Ressource wie Google-, Facebook- oder Microsoft-Identität an. Weitere Informationen finden Sie unter Authentifizieren mit der Office-Dialog-API.
• Mehr Platz auf dem Bildschirm oder sogar eine Vollbildansicht für einige Aufgaben in Ihrem Add-In bereitzustellen.
• Hosten Sie ein Video, das zu klein wäre, wenn es sich auf einen Aufgabenbereich beschränken würde.
• Fehler-, Fortschritts- oder Eingabebildschirm anzeigen.

In der folgenden Abbildung ist ein Beispiel für ein Dialogfeld dargestellt.

Das Dialogfeld wird immer in der Mitte des Bildschirms geöffnet. Der Benutzer kann es verschieben und seine Größe ändern. Das Fenster ist nicht modal . Ein Benutzer kann weiterhin sowohl mit dem Dokument in der Office-Anwendung als auch mit der Seite im Aufgabenbereich interagieren, sofern vorhanden.

Öffnen eines Dialogfelds aus einer Hostseite

Die Office-JavaScript-APIs enthalten ein Dialog-Objekt und zwei Funktionen im Office.context.ui-Namespace.

Um ein Dialogfeld zu öffnen, ruft Ihr Code, in der Regel eine Seite in einem Aufgabenbereich, die displayDialogAsync-Methode auf und übergibt die URL der Ressource, die Sie öffnen möchten. Die Seite, auf der Sie diese Methode aufrufen, wird als "Hostseite" bezeichnet. Wenn Sie diese Methode beispielsweise in einem Skript in index.html einem Aufgabenbereich aufrufen, ist die Hostseite des Dialogfelds, index.html die die Methode öffnet.

Die im Dialogfeld geöffnete Ressource ist normalerweise eine Seite. Es kann sich aber auch um eine Controllermethode in einer MVC-Anwendung, eine Route, eine Webdienstmethode oder eine beliebige andere Ressource handeln. In diesem Artikel bezieht sich "Seite" oder "Website" auf die Ressource im Dialogfeld. Der folgende Code ist ein einfaches Beispiel.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html");

• Die URL verwendet das HTTP-S-Protokoll. Dieses Protokoll ist für alle Seiten erforderlich, die in einem Dialogfeld geladen werden, nicht nur für die erste geladene Seite.
• Die Domäne des Dialogfelds ist mit der Domäne der Hostseite identisch, die die Seite in einem Aufgabenbereich oder die Funktionsdatei eines Add-In-Befehls sein kann. Die Seite, die Controllermethode oder eine andere Ressource, die Sie an die displayDialogAsync Methode übergeben, muss sich in derselben Domäne wie die Hostseite befinden.

Nachdem die erste Seite (oder andere Ressource) geladen wurde, kann ein Benutzer über Links oder eine andere Benutzeroberfläche zu einer beliebigen Website (oder anderen Ressource) navigieren, die HTTPS verwendet. Sie können die erste Seite auch so entwerfen, dass sofort eine Umleitung zu einer anderen Website erfolgt.

Standardmäßig nimmt das Dialogfeld 80 % der Höhe und Breite des Gerätebildschirms ein, Sie können jedoch unterschiedliche Prozentsätze festlegen, indem Sie ein Konfigurationsobjekt an die Methode übergeben, wie im folgenden Beispiel gezeigt.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });

Ein Beispiel-Add-In, das dies tut, finden Sie unter Excel-Tutorial – abgeschlossen. Weitere Beispiele, die displayDialogAsyncverwenden, finden Sie unter Codebeispiele.

Legen Sie beide Werte auf 100 % fest, um eine Vollbildansicht zu erhalten. Das effektive Maximum beträgt 99,5 %, und das Fenster ist weiterhin verschiebbar und in der Größe veränderbar.

Sie können immer nur ein Dialogfeld aus einem Hostfenster öffnen. Bei dem Versuch, ein weiteres Dialogfeld zu öffnen, wird ein Fehler angezeigt. Wenn ein Benutzer beispielsweise ein Dialogfeld von einem Aufgabenbereich aus öffnet, kann er kein zweites Dialogfeld von einer anderen Seite im Aufgabenbereich öffnen. Wenn jedoch ein Dialogfeld über einen Add-In-Befehl geöffnet wird, öffnet der Befehl jedes mal, wenn er ausgewählt wird, eine neue (nicht angezeigte) HTML-Datei. Durch diesen Vorgang wird ein neues (unsichtbares) Hostfenster erstellt, sodass jedes dieser Fenster ein eigenes Dialogfeld öffnen kann. Weitere Informationen finden Sie unter Fehler von displayDialogAsync.

Nutzen einer Leistungsoption in Office im Web

Die displayInIframe Eigenschaft ist eine zusätzliche Eigenschaft im Konfigurationsobjekt, das Sie übergeben displayDialogAsync. Wenn Sie diese Eigenschaft festlegen true und das Add-In in einem in Office im Web geöffneten Dokument ausgeführt wird, wird das Dialogfeld als unverankerter iFrame und nicht als unabhängiges Fenster geöffnet. Durch diesen Ansatz wird das Dialogfeld schneller geöffnet. Im folgenden Beispiel wird gezeigt, wie diese Eigenschaft verwendet wird.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20, displayInIframe: true });

Der Standardwert ist false. Er hat denselben Effekt wie das völlige Weglassen der Eigenschaft. Wenn das Add-In nicht in Office im Web ausgeführt wird, wird die displayInIframe Eigenschaft ignoriert.

Senden von Informationen vom Dialogfeld an die Hostseite

Der Code im Dialogfeld verwendet die messageParent-Funktion , um eine Zeichenfolgennachricht an die Hostseite zu senden. Bei der Zeichenfolge kann es sich um ein Wort, einen Satz, einen XML-BLOB, eine JSON-Zeichenfolge oder eine andere Zeichenfolge handeln, die in eine Zeichenfolge serialisiert oder in eine Zeichenfolge umgewandelt werden kann. Um die messageParent Methode verwenden zu können, muss das Dialogfeld zuerst die Office JavaScript-API initialisieren.

Im folgenden Beispiel wird gezeigt, wie Office JS initialisiert und eine Nachricht an die Hostseite gesendet wird.

Office.onReady(() => {
   // Add any initialization code for your dialog here.
});

// Called when dialog signs in the user.
function userSignedIn() {
    Office.context.ui.messageParent(true.toString());
}

Im nächsten Beispiel wird gezeigt, wie eine JSON-Zeichenfolge zurückgegeben wird, die Profilinformationen enthält.

function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

Die messageParent Funktion ist eine von nur zwei Office JS-APIs, die Sie im Dialogfeld aufrufen können. Die andere JS-API, die Sie im Dialogfeld aufrufen können, ist Office.context.requirements.isSetSupported. Weitere Informationen dazu finden Sie unter "Angeben von Office-Anwendungen und API-Anforderungen". Im Dialogfeld wird diese API jedoch im unbefristeten Outlook 2016 mit Volumenlizenz (d. h. in der MSI-Version) nicht unterstützt.

Sie müssen die Hostseite für den Empfang der Nachricht konfigurieren. Fügen Sie dem ursprünglichen Aufruf von displayDialogAsynceinen Rückrufparameter hinzu. Der Rückruf weist dem DialogMessageReceived-Ereignis einen Handler zu. Im folgenden Beispiel wird dies veranschaulicht.

let dialog; // Declare dialog as global for use in later functions.
Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

Office übergibt ein AsyncResult-Objekt an den Rückruf. Dieses stellt das Ergebnis des Versuchs zum Öffnen des Dialogfelds dar. Er stellt nicht das Ergebnis von Ereignissen im Dialogfeld dar. Weitere Informationen zu diesem Unterschied finden Sie unter Behandeln von Fehlern und Ereignissen.

• Die value-Eigenschaft der asyncResult ist auf ein Dialog-Objekt festgelegt, das auf der Hostseite und nicht im Ausführungskontext des Dialogfelds vorhanden ist.
• Die processMessage Funktion behandelt das Ereignis. Sie können dieser einen beliebigen Namen geben.
• Die dialog-Variable wird mit einem größeren Bereich als der Rückruf deklariert, da auch in processMessage darauf verwiesen wird.

Das folgende Beispiel zeigt einen einfachen Handler für das DialogMessageReceived Ereignis.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    showUserName(messageFromDialog.name);
}

Office übergibt dasarg-Objekt an den Handler. Seine message Eigenschaft ist die Zeichenfolge, die durch den Aufruf von messageParent im Dialogfeld gesendet wird. In diesem Beispiel handelt es sich um eine Zeichenfolgendarstellung des Profils eines Benutzers aus einem Dienst, z. B. Microsoft-Konto oder Google, sodass es wieder in ein Objekt mit deserialisiert wird JSON.parse. Die showUserName Implementierung wird nicht angezeigt. Möglicherweise wird eine personalisierte Willkommensnachricht im Aufgabenbereich angezeigt.

Nach Abschluss der Benutzerinteraktion mit dem Dialogfeld sollte das Dialogfeld vom Meldungshandler geschlossen werden, wie im folgenden Beispiel dargestellt.

function processMessage(arg) {
    dialog.close();
    // Add code to process the message here.
}

Das dialog-Objekt muss dasselbe sein, das vom Aufruf von displayDialogAsync zurückgegeben wird. Deklarieren Sie das dialog Objekt als globale Variable. Sie können das dialog Objekt auch mit einer anonymen Rückruffunktion auf den displayDialogAsync Aufruf beschränken, wie im folgenden Beispiel gezeigt. Im Beispiel muss das Dialogfeld nicht geschlossen werden, processMessage da die close Methode in der anonymen Rückruffunktion aufgerufen wird.

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

Wenn das Add-In nach dem Empfang der Meldung eine andere Seite im Aufgabenbereich öffnen muss, verwenden Sie die window.location.replace Methode (oder window.location.href) als letzte Zeile des Handlers. Im folgenden Beispiel wird dies veranschaulicht.

function processMessage(arg) {
    // Add code to process the message here.
    window.location.replace("/newPage.html");
    // Alternatively, use the following:
    // window.location.href = "/newPage.html";
}

Ein Beispiel für ein solches Add-In finden Sie unter Einfügen von Excel-Diagrammen mit Microsoft Graph in einem PowerPoint-Add-In.

Bedingtes Messaging

Da Sie mehrere messageParent Aufrufe über das Dialogfeld senden können, Sie aber nur einen Handler auf der Hostseite für das DialogMessageReceived Ereignis haben, muss der Handler bedingte Logik verwenden, um verschiedene Nachrichten zu unterscheiden. Wenn ein Benutzer im Dialogfeld beispielsweise aufgefordert wird, sich bei einem Identitätsanbieter wie Microsoft-Konto oder Google anzumelden, wird das Profil des Benutzers als Nachricht gesendet. Wenn die Authentifizierung fehlschlägt, sendet das Dialogfeld Fehlerinformationen an die Hostseite, wie im folgenden Beispiel.

if (loginSuccess) {
    const userProfile = getProfile();
    const messageObject = { messageType: "signinSuccess", profile: userProfile };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
} else {
    const errorDetails = getError();
    const messageObject = { messageType: "signinFailure", error: errorDetails };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Beachten Sie zum vorherigen Beispiel:

• Die loginSuccess Variable wird initialisiert, indem die HTTP-Antwort vom Identitätsanbieter gelesen wird.
• Die Implementierung der getProfilegetError und-Funktionen wird nicht gezeigt. Beide rufen Daten von einem Abfrageparameter oder aus dem Text der HTTP-Antwort ab.
• Anonyme Objekte unterschiedlicher Typen werden in Abhängigkeit davon gesendet, ob die Anmeldung erfolgreich war. Beide weisen eine messageType-Eigenschaft auf, eine verfügt aber über eine profile-Eigenschaft und die andere über eine error-Eigenschaft.

Der Handlercode auf der Hostseite verwendet den Wert der messageType-Eigenschaft für die Verzweigung, wie im folgenden Beispiel dargestellt. Beachten Sie, dass die showUserName-Funktion dieselbe wie im vorherigen Beispiel ist, und dass die showNotification-Funktion den Fehler in der Benutzeroberfläche der Hostseite anzeigt.

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "signinSuccess") {
        dialog.close();
        showUserName(messageFromDialog.profile.name);
        window.location.replace("/newPage.html");
    } else {
        dialog.close();
        showNotification("Unable to authenticate user: " + messageFromDialog.error);
    }
}

Die showNotification Implementierung wird nicht angezeigt. Möglicherweise wird der Status in einer Benachrichtigungsleiste im Aufgabenbereich angezeigt.

Domänenübergreifendes Messaging an die Hostlaufzeit

Nachdem das Dialogfeld geöffnet wurde, kann entweder das Dialogfeld oder die übergeordnete Runtime von der Domäne des Add-Ins weg navigieren. Wenn eines dieser Dinge passiert, schlägt ein Aufruf von messageParent fehl, es sei denn, Ihr Code gibt die Domäne der übergeordneten Laufzeit an. Fügen Sie dem Aufruf messageParent von einen DialogMessageOptions-Parameter hinzu, um die Domäne anzugeben. Dieses Objekt verfügt über eine targetOrigin Eigenschaft, die die Domäne angibt, an die die Nachricht gesendet werden soll. Wenn Sie den Parameter nicht verwenden, geht Office davon aus, dass es sich bei dem Ziel um dieselbe Domäne handelt, die derzeit vom Dialogfeld gehostet wird.

Im folgenden Beispiel wird gezeigt, wie Sie eine domänenübergreifende Nachricht senden messageParent .

Office.context.ui.messageParent("Some message", { targetOrigin: "https://resource.contoso.com" });

Wenn die Nachricht keine vertraulichen Daten enthält, können Sie den targetOrigin Wert auf "*" setzen, sodass sie an eine beliebige Domäne gesendet werden kann. Im folgenden Beispiel wird dies veranschaulicht.

Office.context.ui.messageParent("Some message", { targetOrigin: "*" });

Übergeben von Informationen an das Dialogfeld

Ihr Add-In kann Nachrichten von der Hostseite mithilfe von Dialog.messageChild an ein Dialogfeld senden.

Verwendung messageChild() von der Hostseite

Wenn Sie die Office Dialog-API aufrufen, um ein Dialogfeld zu öffnen, gibt sie ein Dialog-Objekt zurück. Weisen Sie dieses Objekt einer Variablen mit globalem Bereich zu, sodass Sie von anderen Funktionen aus darauf verweisen können. Im folgenden Beispiel wird dies veranschaulicht.

let dialog; // Declare as global variable.
Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html",
    (asyncResult) => {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
);

function processMessage(arg) {
    dialog.close();

    // Add code to process the message here.

}

Dieses Dialog Objekt verfügt über eine messageChild-Methode , die eine beliebige Zeichenfolge, einschließlich Zeichenfolgendaten, an das Dialogfeld sendet. Diese Methode löst ein DialogParentMessageReceived Ereignis in dem Dialogfeld aus. Ihr Code sollte dieses Ereignis behandeln, wie im nächsten Abschnitt gezeigt.

Stellen Sie sich ein Szenario vor, in dem die Benutzeroberfläche des Dialogfelds mit dem derzeit aktiven Excel-Arbeitsblatt verknüpft ist und die Position dieses Arbeitsblatts relativ zu den anderen Arbeitsblättern. Sendet im folgenden Beispiel worksheetPropertiesChanged die Eigenschaften des aktiven Arbeitsblatts an das Dialogfeld. Die Daten werden in Zeichenfolgen umgewandelt, sodass sie an übergeben messageChildwerden können.

await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    worksheet.load();
    await context.sync();
    worksheetPropertiesChanged(worksheet);
});

...

function worksheetPropertiesChanged(currentWorksheet) {
    const messageToDialog = JSON.stringify(currentWorksheet);
    dialog.messageChild(messageToDialog);
}

Behandeln von DialogParentMessageReceived im Dialogfeld

Registrieren Sie im JavaScript des Dialogfelds einen Handler für das DialogParentMessageReceived Ereignis mithilfe der UI.addHandlerAsync-Methode . In der Regel registrieren Sie den Handler in der Office.onReady- oder Office.initialize-Funktion, wie im folgenden Beispiel gezeigt. (Ein robusteres Beispiel finden Sie weiter unten in diesem Artikel.)

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(Office.EventType.DialogParentMessageReceived,onMessageFromParent);
});

Definieren Sie dann den onMessageFromParent Handler. Der folgende Code setzt das Beispiel aus dem vorherigen Abschnitt fort. Beachten Sie, dass Office ein Argument an den Handler übergibt und dass die message Eigenschaft des Argument-Objekts die Zeichenfolge von der Hostseite enthält. In diesem Beispiel wird die Nachricht wieder in ein Objekt konvertiert und jQuery wird verwendet, um die obere Überschrift des Dialogfelds so festzulegen, dass sie mit dem neuen Arbeitsblattnamen übereinstimmt.

function onMessageFromParent(arg) {
    const messageFromParent = JSON.parse(arg.message);
    document.querySelector('h1').textContent = messageFromParent.name;
}

Es empfiehlt sich zu überprüfen, ob Ihr Handler ordnungsgemäß registriert ist. Sie können dies tun, indem Sie einen Rückruf an die addHandlerAsync Methode übergeben. Dieser Rückruf wird ausgeführt, wenn der Versuch, den Handler zu registrieren, abgeschlossen ist. Verwenden Sie den Handler, um einen Fehler zu protokollieren oder anzuzeigen, wenn der Handler nicht erfolgreich registriert wurde. Im folgenden Beispiel wird dies veranschaulicht. Beachten Sie, dass reportError es sich um eine hier nicht definierte Funktion handelt, die den Fehler protokolliert oder anzeigt.

Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
        reportError(asyncResult.error.message);
    }
}

Bedingtes Messaging von der übergeordneten Seite zum Dialogfeld

Da die Hostseite mehrere messageChild Aufrufe ausführen kann, das Dialogfeld jedoch nur einen Handler für das DialogParentMessageReceived Ereignis hat, muss der Handler bedingte Logik verwenden, um verschiedene Nachrichten zu unterscheiden. Sie können diese bedingte Logik so strukturieren, dass sie genau der Struktur des bedingten Messagings entspricht, wenn das Dialogfeld eine Nachricht an die Hostseite sendet, wie unter Bedingtes Messaging beschrieben.

Domänenübergreifendes Messaging an die Dialoglaufzeit

Nachdem das Dialogfeld geöffnet wurde, kann entweder das Dialogfeld oder die übergeordnete Runtime von der Domäne des Add-Ins weg navigieren. Wenn eines dieser Dinge passiert, schlagen messageChild Aufrufe fehl, es sei denn, der Code gibt die Domäne der Dialoglaufzeit an. Fügen Sie dem Aufruf messageChild von einen DialogMessageOptions-Parameter hinzu, um die Domäne anzugeben. Dieses Objekt verfügt über eine targetOrigin Eigenschaft, die die Domäne angibt, an die die Nachricht gesendet werden soll. Wenn Sie den Parameter nicht verwenden, geht Office davon aus, dass es sich bei dem Ziel um dieselbe Domäne handelt, die derzeit von der übergeordneten Runtime gehostet wird.

Im folgenden Beispiel wird gezeigt, wie Sie eine domänenübergreifende Nachricht senden messageChild .

dialog.messageChild(messageToDialog, { targetOrigin: "https://resource.contoso.com" });

Wenn die Nachricht keine vertraulichen Daten enthält, können Sie den targetOrigin Wert auf "*" setzen, sodass sie an eine beliebige Domäne gesendet werden kann. Im folgenden Beispiel wird gezeigt, wie Sie die targetOrigin.

dialog.messageChild(messageToDialog, { targetOrigin: "*" });

Das Manifest des Add-Ins gibt vertrauenswürdige Domänen an. Geben Sie im einheitlichen Manifest für Microsoft 365 diese Domäne in der Eigenschaft "validDomains" an. Geben Sie im Nur-Add-In-Manifest diese Domäne im <AppDomains> Element an.

Die Laufzeit, die das Dialogfeld hostet, kann jedoch nicht auf das Manifest zugreifen und somit bestimmen, ob die Domäne , aus der die Nachricht stammt, vertrauenswürdig ist. Sie müssen den DialogParentMessageReceived Handler verwenden, um dies zu ermitteln. Das Objekt, das an den Handler übergeben wird, enthält die Domäne, die derzeit im übergeordneten Element origin als Eigenschaft gehostet wird. Im folgenden Beispiel wird gezeigt, wie die Eigenschaft verwendet wird.

function onMessageFromParent(arg) {
    if (arg.origin === "https://addin.fabrikam.com") {
        // Process the message.
    } else {
        // Signal the parent page to close the dialog.
        const messageObject = { messageType: "untrustedDomain" };
        Office.context.ui.messageParent(messageObject);
    }
}

Ihr Code könnte z. B. die Office.onReady- oder Office.initialize-Funktion verwenden, um ein Array vertrauenswürdiger Domänen in einer globalen Variablen zu speichern. Die arg.origin Eigenschaft könnte dann im Handler mit dieser Liste abgeglichen werden.

Windows Registry Editor Version 5.00

[HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\WEF\AllowedDialogCommunicationDomains]
"My trusted domain"="https://www.contoso.com"
"Another trusted domain"="https://fabrikam.com"

Schließen des Dialogfelds

Sie können dem Dialogfeld eine Schaltfläche hinzufügen, die es schließt. Dazu sollte messageParent der Click-Ereignishandler für die Schaltfläche der Hostseite mitteilen, dass auf die Schaltfläche geklickt wurde. Das folgende Beispiel zeigt, wie diese Funktionalität implementiert wird.

function closeButtonClick() {
    const messageObject = { messageType: "dialogClosed" };
    const jsonMessage = JSON.stringify(messageObject);
    Office.context.ui.messageParent(jsonMessage);
}

Der Hostseitenhandler für DialogMessageReceived Anrufe dialog.close, wie in diesem Beispiel gezeigt. (In den vorherigen Beispielen wird gezeigt, wie das dialog-Objekt initialisiert wird.)

function processMessage(arg) {
    const messageFromDialog = JSON.parse(arg.message);
    if (messageFromDialog.messageType === "dialogClosed") {
       dialog.close();
    }
}

Auch wenn Sie keine eigene Benutzeroberfläche zum Schließen des Dialogfelds hinzufügen, kann ein Endbenutzer das Dialogfeld schließen, indem er das X in der oberen rechten Ecke auswählt. Diese Aktion löst das DialogEventReceived-Ereignis aus. Wenn Ihr Hostbereich wissen muss, wann dieses Ereignis eintritt, sollte es einen Handler für dieses Ereignis deklarieren. Weitere Informationen finden Sie unter Fehler und Ereignisse im Dialogfeld.

window.open nicht verwenden

Verwenden Sie nicht die Standardbrowser-Methode window.open() zum Öffnen von Dialogfeldern oder Popup-Fenstern in Office-Add-Ins. Die window.open() Methode funktioniert nicht zuverlässig in den verschiedenen Browser- und Webview-Steuerelementen, in denen Office-Add-Ins ausgeführt werden. Die folgenden Probleme können bei window.open()auftreten.

• Funktioniert nicht in iframe-Kontexten: Wenn Ihr Add-In in Office im Web ausgeführt wird, befindet sich der Aufgabenbereich in einem iframe. Aus Sicherheitsgründen blockieren viele Browser Aufrufe von iframes oder schränken sie stark ein window.open() .
• Durch Popupblocker blockiert: Browserbasierte Popupblocker blockieren window.open() Anrufe, und das Verhalten variiert je nach Browser.
• Inkonsistentes Webview-Verhalten: Die eingebetteten Webview-Steuerelemente, die von Desktop-Office-Anwendungen verwendet werden, verhalten sich anders als window.open() vollständige Browser, was zu unvorhersehbarem Verhalten führt.
• Keine plattformübergreifende Garantie: Selbst wenn window.open() es auf einer Plattform (z. B. Windows-Desktop) funktioniert, kann es auf einer anderen Plattform (z. B. Office im Web oder Mac) vollständig fehlschlagen.

Verwenden Sie stattdessen immer die Office-Dialog-API. Die Office-Dialog-API (Office.context.ui.displayDialogAsync) wurde speziell entwickelt, um auf allen Office-Plattformen und Laufzeitumgebungen konsistent zu funktionieren. Es bietet zuverlässige Dialogfunktionen, die unabhängig davon funktionieren, ob das Add-In in einem Browser, einem Webview-Steuerelement oder einem iframe ausgeführt wird.

Um externe URLs in einem separaten Browserfenster zu öffnen (nicht zur Authentifizierung oder zum Datenaustausch mit Ihrem Add-In), verwenden Sie stattdessen die Office.context.ui.openBrowserWindow(url) Methode, bei der url es sich in der Regel um eine HTTPS-URL handelt.

Codebeispiele

In allen folgenden Beispielen wird displayDialogAsyncverwendet. Einige verfügen über NodeJS-basierte Server und andere über ASP.NET/IIS-based Server, aber die Logik der Verwendung der Methode ist dieselbe, unabhängig davon, wie die Serverseite des Add-Ins implementiert ist.

• Excel-Tutorial – abgeschlossen
• Verwalten des Menübandes und der Aufgabenbereich-Benutzeroberfläche, und Code auf einem offenen Dokument ausführen
• Abrufen von OneDrive-Daten mithilfe von Microsoft Graph und MSAL.net in einem Office-Add-In
• Abrufen von OneDrive-Daten mithilfe von Microsoft Graph und MSAL.js in einem Office-Add-In
• Office Add-In – SAAS-Monetarisierungsbeispiel
• Abrufen von Excel-Arbeitsmappen mithilfe von Microsoft Graph und MSAL in einem Outlook-Add-In
• Outlook-Add-In-SSO

Siehe auch

• Dialog-API-Anforderungssätze
• Bewährte Methoden und Regeln für die Office-Dialogfeld-API
• Authentifizieren mit der Office-Dialogfeld-API
• Verwenden des Office-Dialogfelds zum Anzeigen eines Videos
• Fehler- und Ereignisbehandlung im Office-Dialogfeld
• Runtimes in Office-Add-Ins