Office.UI interface

Fügt dem -Objekt unter Verwendung des angegebenen Ereignistyps einen Ereignishandler hinzu.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameter

Gibt zurück

Hinweise

Anforderungssatz: DialogAPI 1.2

Sie können mehrere Ereignishandler für den angegebenen Ereignistyp hinzufügen, solange der Name jeder Ereignishandlerfunktion eindeutig ist.

Fügt dem -Objekt unter Verwendung des angegebenen Ereignistyps einen Ereignishandler hinzu.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;

Parameter

Gibt zurück

Hinweise

Anforderungssatz: DialogAPI 1.2

Sie können mehrere Ereignishandler für den angegebenen Ereignistyp hinzufügen, solange der Name jeder Ereignishandlerfunktion eindeutig ist.

Beispiele

// The following example shows how to add an event handler for the DialogParentMessageReceived event.
Office.onReady(() => {
    Office.context.ui.addHandlerAsync(
        Office.EventType.DialogParentMessageReceived,
        onMessageFromParent,
        onRegisterMessageComplete
    );
});

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

function onRegisterMessageComplete(asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
    }
}

Schließt den UI-Container, in dem der JavaScript-Code ausgeführt wird.

closeContainer(): void;

Gibt zurück

Hinweise

Anwendungen: Excel, Outlook (Mindestanforderungssatz: Postfach 1.5), PowerPoint, Word

Anforderungssätze:

• DialogAPI

• Mailbox 1.5

Das Verhalten dieser Methode wird wie folgt angegeben:

• Von einer Befehlsschaltfläche ohne Benutzeroberfläche aufgerufen: Keine Auswirkung. Jedes über displayDialogAsync geöffnete Dialogfeld bleibt geöffnet.

• Aus einem Aufgabenbereich aufgerufen: Der Aufgabenbereich wird geschlossen. Jedes von displayDialogAsync geöffnete Dialogfeld wird ebenfalls geschlossen. Wenn der Aufgabenbereich das Anheften unterstützt und vom Benutzer angeheftet wurde, wird er nicht angeheftet.

• Von einer Modulerweiterung aufgerufen: Kein Effekt.

Beispiele

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();

Zeigt ein Dialogfeld an, um Informationen vom Benutzer anzuzeigen oder zu sammeln oder um die Webnavigation zu erleichtern.

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;

Parameter

Gibt zurück

Hinweise

Anwendungen: Excel, Outlook, PowerPoint, Word

Anforderungssätze:

• DialogAPI

• Mailbox 1.4

Diese Methode ist im DialogApi-Anforderungssatz für Excel-, PowerPoint- oder Word-Add-Ins und im Postfachanforderungssatz 1.4 für Outlook verfügbar. Weitere Informationen zum Angeben eines Anforderungssatzes in Ihrem Manifest finden Sie unter Angeben von Office-Anwendungen und API-Anforderungen, wenn Sie das reine Add-In-Manifest verwenden. Wenn Sie das einheitliche Manifest für Microsoft 365 verwenden, lesen Sie Office-Add-Ins mit dem einheitlichen App-Manifest für Microsoft 365.

Die erste Seite muss sich in derselben Domäne wie die übergeordnete Seite befinden (der startAddress-Parameter). Nachdem die Startseite geladen wurde, können Sie zu anderen Domänen wechseln.

Alle Seitenaufrufe Office.context.ui.messageParent müssen sich auch in derselben Domäne wie die übergeordnete Seite befinden.

Überlegungen zum Entwurf:

Die folgenden Entwurfsüberlegungen gelten für Dialogfelder.

• Ein Office-Add-In-Aufgabenbereich kann jederzeit nur ein Dialogfeld geöffnet haben. Über Add-In-Befehle (benutzerdefinierte Menübandschaltflächen oder Menüelemente) können mehrere Dialogfelder gleichzeitig geöffnet werden.

• Jedes Dialogfeld kann vom Benutzer verschoben und in der Größe geändert werden.

• Jedes Dialogfeld wird beim Öffnen auf dem Bildschirm zentriert.

• Dialogfelder werden oben in der Anwendung und in der Reihenfolge angezeigt, in der sie erstellt wurden.

Verwenden Sie ein Dialogfelder zu folgenden Zwecken:

• Anzeigen von Authentifizierungsseiten zum Sammeln von Benutzeranmeldeinformationen

• Anzeigen eines Fehler-/Status-/Eingabebildschirms aus einem ShowTaskpane- oder ExecuteAction-Befehl.

• Vorübergehende Vergrößerung der Oberfläche, die einem Benutzer zum Durchführen einer Aufgabe zur Verfügung steht.

Verwenden Sie ein Dialogfeld nicht zur Interaktion mit einem Dokument. Verwenden Sie stattdessen einen Aufgabenbereich.

displayDialogAsync-Fehler

In der Rückruffunktion, die an die displayDialogAsync-Methode übergeben wird, können Sie die Eigenschaften des AsyncResult-Objekts verwenden, um die folgenden Informationen zurückzugeben.

Beispiele

// The following example shows how to open a dialog with a specified size. It also shows
// how to register a function to handle the message when Office.UI.messageParent() is called
// in the dialog. The implementation of the processMessage() function is omitted.

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

// The following example does the same thing in TypeScript.

Office.context.ui.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 },
    (asyncResult: Office.AsyncResult) => {
        const dialog: Office.Dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, (arg: string) => {
            dialog.close();
            processMessage(arg);
        });
    }
);

Zeigt ein Dialogfeld an, um Informationen vom Benutzer anzuzeigen oder zu sammeln oder um die Webnavigation zu erleichtern.

displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): void;

Parameter

Gibt zurück

Hinweise

Anwendungen: Excel, Outlook, PowerPoint, Word

Anforderungssätze:

• DialogAPI

• Mailbox 1.4

Diese Methode ist im DialogApi-Anforderungssatz für Excel-, PowerPoint- oder Word-Add-Ins und im Postfachanforderungssatz 1.4 für Outlook verfügbar. Weitere Informationen zum Angeben eines Anforderungssatzes in Ihrem Manifest finden Sie unter Angeben von Office-Anwendungen und API-Anforderungen, wenn Sie das reine Add-In-Manifest verwenden. Wenn Sie das einheitliche Manifest für Microsoft 365 verwenden, lesen Sie Office-Add-Ins mit dem einheitlichen App-Manifest für Microsoft 365.

Die erste Seite muss sich in derselben Domäne wie die übergeordnete Seite befinden (der startAddress-Parameter). Nachdem die Startseite geladen wurde, können Sie zu anderen Domänen wechseln.

Alle Seitenaufrufe Office.context.ui.messageParent müssen sich auch in derselben Domäne wie die übergeordnete Seite befinden.

Überlegungen zum Entwurf:

Die folgenden Entwurfsüberlegungen gelten für Dialogfelder.

• Ein Office-Add-In-Aufgabenbereich kann jederzeit nur ein Dialogfeld geöffnet haben. Über Add-In-Befehle (benutzerdefinierte Menübandschaltflächen oder Menüelemente) können mehrere Dialogfelder gleichzeitig geöffnet werden.

• Jedes Dialogfeld kann vom Benutzer verschoben und in der Größe geändert werden.

• Jedes Dialogfeld wird beim Öffnen auf dem Bildschirm zentriert.

• Dialogfelder werden oben in der Anwendung und in der Reihenfolge angezeigt, in der sie erstellt wurden.

Verwenden Sie ein Dialogfelder zu folgenden Zwecken:

• Anzeigen von Authentifizierungsseiten zum Sammeln von Benutzeranmeldeinformationen

• Anzeigen eines Fehler-/Status-/Eingabebildschirms aus einem ShowTaskpane- oder ExecuteAction-Befehl.

• Vorübergehende Vergrößerung der Oberfläche, die einem Benutzer zum Durchführen einer Aufgabe zur Verfügung steht.

Verwenden Sie ein Dialogfeld nicht zur Interaktion mit einem Dokument. Verwenden Sie stattdessen einen Aufgabenbereich.

displayDialogAsync-Fehler

In der Rückruffunktion, die an die displayDialogAsync-Methode übergeben wird, können Sie die Eigenschaften des AsyncResult-Objekts verwenden, um die folgenden Informationen zurückzugeben.

Übermittelt eine Nachricht vom Dialogfeld an die übergeordnete/öffnende Seite.

messageParent(message: string, messageOptions?: DialogMessageOptions): void;

Parameter

Gibt zurück

Hinweise

Anwendungen: Excel, Outlook, PowerPoint, Word

Anforderungssätze:

• DialogAPI

• Mailbox 1.4

• Wenn der messageOptions Parameter verwendet wird, ist auch DialogOrigin 1.1 erforderlich.

Beispiele

// The following example shows how to send a JSON string to the parent. The profile object
// is returned from some website when a user signs into it.
function userProfileSignedIn(profile) {
    const profileMessage = {
        "name": profile.name,
        "email": profile.email,
    };
    Office.context.ui.messageParent(JSON.stringify(profileMessage));
}

Öffnet ein Browserfenster und lädt die angegebene URL.

openBrowserWindow(url: string): void;

Parameter

Gibt zurück

Hinweise

Anforderungssatz: OpenBrowserWindowAPI 1.1

Beispiele

// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();