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 Identity 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 auf einen Aufgabenbereich beschränkt wäre.
• Anzeigen eines Fehler-, Status- oder Eingabebildschirms.

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 im Skript index.html für in einem Aufgabenbereich aufrufen, index.html ist die Hostseite des Dialogfelds, das von der Methode geöffnet wird.

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 In einem Dialogfeld geladenen Seiten obligatorisch, 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 eine andere Ressource) geladen wurde, kann ein Benutzer Links oder eine andere Benutzeroberfläche verwenden, um zu jeder Website (oder anderen Ressource) zu 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 verwenden displayDialogAsync, finden Sie unter Codebeispiele.

Legen Sie beide Werte auf 100 % fest, um eine Vollbildansicht zu erhalten. Der effektive Höchstwert beträgt 99,5 %, und das Fenster kann weiterhin verschoben werden und die Größe kann geändert werden.

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 aus einem Aufgabenbereich ö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. Dieser Prozess erstellt ein neues (unbekanntes) Hostfenster, sodass jedes dieser Fenster ein eigenes Dialogfeld starten 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, die Sie an displayDialogAsyncübergeben. Wenn Sie diese Eigenschaft auf true festlegen und das Add-In in einem Dokument ausgeführt wird, das in Office im Web geöffnet wurde, wird das Dialogfeld als unverankertes iFrame und nicht als unabhängiges Fenster geöffnet. Dadurch wird das Dialogfeld schneller geöffnet. Im folgenden Beispiel wird die Verwendung dieser Eigenschaft veranschaulicht.

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

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, ein XML-Blob, einen json-Code mit Zeichenfolgen oder eine beliebige andere Art 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.

Das folgende Beispiel zeigt, wie Sie Office JS initialisieren und eine Nachricht an die Hostseite senden.

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 hierzu finden Sie unter Angeben von Office-Anwendungen und API-Anforderungen. Im Dialogfeld wird diese API jedoch in volumenlizenzierten unbefristeten Outlook 2016 (d. b. der MSI-Version) nicht unterstützt.

Sie müssen die Hostseite so konfigurieren, dass die Nachricht empfangen wird. 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. Es 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 vom Aufruf von messageParent im Dialogfeld gesendet wird. In diesem Beispiel handelt es sich um eine zeichenfolgenweise Darstellung des Profils eines Benutzers aus einem Dienst, z. B. Microsoft-Konto oder Google, sodass es mit JSON.parsewieder in ein Objekt deserialisiert wird. 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 auf den displayDialogAsync Aufruf mit einer anonymen Rückruffunktion festlegen, 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 Nachricht eine andere Seite des Aufgabenbereichs ö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 aus dem Dialogfeld senden können, 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 beispielsweise das Dialogfeld einen Benutzer auffordert, sich bei einem Identitätsanbieter wie einem 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 gezeigt.

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 durch Lesen der HTTP-Antwort vom Identitätsanbieter initialisiert.
• Die Implementierung der getProfile Funktionen und getError wird nicht angezeigt. 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 status in einer Benachrichtigungsleiste im Aufgabenbereich angezeigt.

Domänenübergreifendes Messaging an die Hostruntime

Nachdem das Dialogfeld geöffnet wurde, kann entweder der Dialog oder die übergeordnete Runtime von der Domäne des Add-Ins weg navigieren. Wenn eines dieser Dinge geschieht, schlägt ein Aufruf von messageParent fehl, es sei denn, Ihr Code gibt die Domäne der übergeordneten Runtime an. Fügen Sie dem Aufruf von messageParent 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 das Ziel dieselbe Domäne ist, die der Dialog derzeit hosten wird.

Das folgende Beispiel zeigt, wie sie verwenden messageParent , um eine domänenübergreifende Nachricht zu senden.

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

Wenn die Nachricht keine vertraulichen Daten enthält, können Sie auf targetOrigin "*" festlegen, sodass es 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 mithilfe von Dialog.messageChild Nachrichten von der Hostseite an ein Dialogfeld senden.

Verwenden von messageChild() der Hostseite

Wenn Sie die Office-Dialogfeld-API aufrufen, um ein Dialogfeld zu öffnen, wird ein Dialog-Objekt zurückgegeben. Weisen Sie dieses Objekt einer Variablen mit globalem Bereich zu, damit Sie von anderen Funktionen 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 alle Zeichenfolgen, einschließlich Zeichenfolgendaten, an das Dialogfeld sendet. Diese Methode löst ein DialogParentMessageReceived -Ereignis im 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 aktuell aktiven Excel-Arbeitsblatt und der Position dieses Arbeitsblatts relativ zu den anderen Arbeitsblättern verknüpft ist. Im folgenden Beispiel worksheetPropertiesChanged sendet die Eigenschaften des aktiven Arbeitsblatts an das Dialogfeld. Die Daten werden zeichenfolgengefälkt, sodass sie an messageChildübergeben werden 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 mithilfe der UI.addHandlerAsync-Methode einen Handler für das DialogParentMessageReceived Ereignis. In der Regel registrieren Sie den Handler in der Office.onReady- oder Office.initialize-Funktion, wie im folgenden Beispiel gezeigt. (Ein robusteres Beispiel ist weiter unten in diesem Artikel enthalten.)

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 Argumentobjekts die Zeichenfolge von der Hostseite enthält. In diesem Beispiel wird die Nachricht in ein -Objekt wiederhergestellt, und jQuery wird verwendet, um die obere Überschrift des Dialogfelds so festzulegen, dass sie dem namen des neuen Arbeitsblatts entspricht.

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. Hierzu können 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 eine Hier nicht definierte Funktion ist, 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 aber nur einen Handler für das DialogParentMessageReceived Ereignis enthält, muss der Handler bedingte Logik verwenden, um verschiedene Nachrichten zu unterscheiden. Sie können diese bedingte Logik auf eine Weise strukturieren, die genau parallel zur 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 Dialogruntime

Nachdem das Dialogfeld geöffnet wurde, kann entweder der Dialog oder die übergeordnete Runtime von der Domäne des Add-Ins weg navigieren. Wenn einer dieser Dinge auftritt, schlagen Aufrufe fehl messageChild , es sei denn, Ihr Code gibt die Domäne der Dialogruntime an. Fügen Sie dem Aufruf von messageChild 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 das Ziel dieselbe Domäne ist, die derzeit von der übergeordneten Runtime gehostet wird.

Das folgende Beispiel zeigt, wie sie verwenden messageChild , um eine domänenübergreifende Nachricht zu senden.

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

Wenn die Nachricht keine vertraulichen Daten enthält, können Sie auf targetOrigin "*" festlegen, sodass es an eine beliebige Domäne gesendet werden kann. Im folgenden Beispiel wird gezeigt, wie festgelegt wird 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 Reinen Add-In-Manifest diese Domäne im -Element an <AppDomains> .

Die Runtime, in der das Dialogfeld gehostet wird, kann jedoch nicht auf das Manifest zugreifen und somit bestimmen, ob die Domäne , von der die Nachricht stammt, vertrauenswürdig ist. Sie müssen den DialogParentMessageReceived Handler verwenden, um dies zu bestimmen. Das an den Handler übergebene Objekt enthält die Domäne, die derzeit im übergeordneten Objekt als - origin Eigenschaft gehostet wird. Das folgende Beispiel zeigt, 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 beispielsweise 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 kann dann anhand dieser Liste im Handler überprüft 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, das es schließt, eine Schaltfläche hinzufügen. Dazu sollte der Click-Ereignishandler für die Schaltfläche verwenden messageParent , um der Hostseite mitzuteilen, dass auf die Schaltfläche geklickt wurde. Im folgenden Beispiel wird gezeigt, 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 Aufrufe 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 er 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 Standardbrowsermethode window.open() , um Dialogfelder oder Popupfenster in Office-Add-Ins zu öffnen. Die window.open() -Methode funktioniert nicht zuverlässig in den verschiedenen Browser- und Webview-Steuerelementen, in denen Office-Add-Ins ausgeführt werden. Möglicherweise treten die folgenden Probleme mit auf window.open().

• 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 oder schränken window.open() viele Browser Aufrufe von iframes stark ein.
• Durch Popupblocker blockiert: Browserbasierte Popupblocker blockieren window.open() Aufrufe, und das Verhalten variiert je nach Browser.
• Inkonsistentes Webansichtsverhalten: Die eingebetteten Webview-Steuerelemente, die von Office-Desktopanwendungen verwendet werden, verhalten sich window.open() anders als bei vollständigen Browsern, was zu unvorhersehbarem Verhalten führt.
• Keine plattformübergreifende Garantie: Selbst wenn window.open() auf einer Plattform (z. B. Windows-Desktop) funktioniert, kann dies auf einer anderen Plattform (z. B. Office im Web oder Mac) vollständig ausfallen.

Verwenden Sie stattdessen immer die Office-Dialog-API. Die Office Dialog-API (Office.context.ui.displayDialogAsync) ist speziell für die konsistente Arbeit auf allen Office-Plattformen und Laufzeitumgebungen konzipiert. Es bietet zuverlässige Dialogfunktionen, die unabhängig davon funktionieren, ob Ihr Add-In in einem Browser, einem Webview-Steuerelement oder einem iframe ausgeführt wird.

Um externe URLs in einem separaten Browserfenster zu öffnen (nicht für die Authentifizierung oder den Datenaustausch mit Ihrem Add-In), verwenden Sie stattdessen die -Methode, wobei url in der Office.context.ui.openBrowserWindow(url) Regel eine HTTPS-URL ist.

Codebeispiele

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

• Excel-Tutorial – Abgeschlossen
• Szenario für freigegebene Excel-Runtime
• Office-Add-In Microsoft Graph ASPNET
• Office Add-in Microsoft Graph React
• Office-Add-In NodeJS SSO
• Office-Add-In ASPNET SSO
• Office-Add-In SAAS-Monetarisierungsbeispiel
• Outlook-Add-In Microsoft Graph ASPNET
• Outlook-Add-In SSO
• Outlook-Add-In-Token-Viewer
• Outlook-Add-In-Nachricht mit Aktionen
• Outlook-Add-In-Freigabe auf OneDrive
• PowerPoint-Add-In Microsoft Graph ASPNET InsertChart

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 Dialogfelds "Office" zum Anzeigen eines Videos
• Fehler- und Ereignisbehandlung im Office-Dialogfeld
• Runtimes in Office-Add-Ins