Office.UI interface

Referenz

Paket:: office

Stellt Objekte und Methoden zum Erstellen und Bearbeiten von Benutzeroberflächenkomponenten wie Dialogfeldern in Ihren Office-Add-Ins bereit.

Eine Anleitung zum Konfigurieren von Dialogfeldern finden Sie unter Verwenden der Dialog-API in Ihren Office-Add-Ins.

Hinweise

Beispiele

TypeScript

// Get an Office.UI object and use it to open a dialog with a specified size. 
const uiContext = Office.context.ui;
uiContext.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });

Methoden

addHandlerAsync(eventType, handler, options, callback)	Fügt dem -Objekt unter Verwendung des angegebenen Ereignistyps einen Ereignishandler hinzu.
addHandlerAsync(eventType, handler, callback)	Fügt dem -Objekt unter Verwendung des angegebenen Ereignistyps einen Ereignishandler hinzu.
closeContainer()	Schließt den UI-Container, in dem der JavaScript-Code ausgeführt wird.
displayDialogAsync(startAddress, options, callback)	Zeigt ein Dialogfeld an, um Informationen vom Benutzer anzuzeigen oder zu sammeln oder um die Webnavigation zu erleichtern.
displayDialogAsync(startAddress, callback)	Zeigt ein Dialogfeld an, um Informationen vom Benutzer anzuzeigen oder zu sammeln oder um die Webnavigation zu erleichtern.
messageParent(message, messageOptions)	Übermittelt eine Nachricht vom Dialogfeld an die übergeordnete/öffnende Seite.
openBrowserWindow(url)	Öffnet ein Browserfenster und lädt die angegebene URL.

Details zur Methode

addHandlerAsync(eventType, handler, options, callback)

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

TypeScript

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

Parameter

eventType: Office.EventType

Gibt den Ereignistyp an, der hinzugefügt werden soll. Dies muss sein Office.EventType.DialogParentMessageReceived.

handler: (result: Office.DialogParentMessageReceivedEventArgs) => void

Die hinzuzufügende Ereignishandlerfunktion, deren einziger Parameter vom Typ Office.DialogParentMessageReceivedEventArgs ist.

options: Office.AsyncContextOptions

Bietet eine Option zum Beibehalten von Kontextdaten eines beliebigen Typs , unverändert, für die Verwendung in einem Rückruf.

callback: (result: Office.AsyncResult<void>) => void

Optional. Eine Funktion, die aufgerufen wird, wenn die Handlerregistrierung zurückgibt, deren einziger Parameter vom Typ Office.AsyncResult ist.

Gibt zurück

void

Hinweise

Anforderungssatz: DialogAPI 1.2

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

addHandlerAsync(eventType, handler, callback)

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

TypeScript

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

Parameter

eventType: Office.EventType

Gibt den Ereignistyp an, der hinzugefügt werden soll. Dies muss sein Office.EventType.DialogParentMessageReceived.

handler: (result: Office.DialogParentMessageReceivedEventArgs) => void

Die hinzuzufügende Ereignishandlerfunktion, deren einziger Parameter vom Typ Office.DialogParentMessageReceivedEventArgs ist.

callback: (result: Office.AsyncResult<void>) => void

Optional. Eine Funktion, die aufgerufen wird, wenn die Handlerregistrierung zurückgibt, deren einziger Parameter vom Typ Office.AsyncResult ist.

Gibt zurück

void

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

TypeScript

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

closeContainer()

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

TypeScript

closeContainer(): void;

Gibt zurück

void

Hinweise

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

Anforderungssätze:

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

TypeScript

// 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();

displayDialogAsync(startAddress, options, callback)

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

TypeScript

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

Parameter

startAddress: string

Akzeptiert die anfängliche vollständige HTTPS-URL, die im Dialogfeld geöffnet wird. Relative URLs dürfen nicht verwendet werden.

options: Office.DialogOptions

Optional. Akzeptiert ein Office.DialogOptions-Objekt zum Definieren der Dialoganzeige.

callback: (result: Office.AsyncResult<Office.Dialog>) => void

Optional. Akzeptiert eine Rückruffunktion zum Verarbeiten des Dialogerstellungsversuchs. Bei erfolgreicher Ausführung ist AsyncResult.value ein Dialog-Objekt.

Gibt zurück

void

Hinweise

Anwendungen: Excel, Outlook, PowerPoint, Word

Anforderungssätze:

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.

Wichtig:

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.
Informationen zu Regeln, Einschränkungen und bewährten Methoden für die Office-Dialog-API finden Sie unter Bewährte Methoden und Regeln für die Office-Dialog-API.
Informationen zu Fehlern und deren Behandlung finden Sie unter Behandeln von Fehlern und Ereignissen im Dialogfeld Office.
Legen Sie in Outlook im Web und dem neuen Outlook unter Windows die eigenschaft window.name beim Konfigurieren eines Dialogfelds in Ihrem Add-In nicht fest. Die window.name -Eigenschaft wird von diesen Outlook-Clients verwendet, um die Funktionalität über Seitenumleitungen hinweg beizubehalten.
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.

Eigenschaft	Verwendung
`AsyncResult.value`	Greift auf das Dialog-Objekt zu.
`AsyncResult.status`	Bestimmen Sie, ob der Vorgang erfolgreich war oder ein Fehler aufgetreten ist.
`AsyncResult.error`	Greifen Sie auf ein Error-Objekt zu, das nach einem fehlgeschlagenen Vorgang Fehlerinformationen bereitstellt.
`AsyncResult.asyncContext`	Greifen Sie auf Ihr benutzerdefiniertes Objekt oder Ihren Wert zu, wenn Sie eines als asyncContext-Parameter übergeben haben.

Beispiele

TypeScript

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

displayDialogAsync(startAddress, callback)

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

TypeScript

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

Parameter

startAddress: string

Akzeptiert die anfängliche vollständige HTTPS-URL, die im Dialogfeld geöffnet wird. Relative URLs dürfen nicht verwendet werden.

callback: (result: Office.AsyncResult<Office.Dialog>) => void

Optional. Akzeptiert eine Rückruffunktion zum Verarbeiten des Dialogerstellungsversuchs. Bei erfolgreicher Ausführung ist AsyncResult.value ein Dialog-Objekt.

Gibt zurück

void

Hinweise

Anwendungen: Excel, Outlook, PowerPoint, Word

Anforderungssätze:

Wichtig:

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.
Informationen zu Regeln, Einschränkungen und bewährten Methoden für die Office-Dialog-API finden Sie unter Bewährte Methoden und Regeln für die Office-Dialog-API.
Informationen zu Fehlern und deren Behandlung finden Sie unter Behandeln von Fehlern und Ereignissen im Dialogfeld Office.
Legen Sie in Outlook im Web und dem neuen Outlook unter Windows die eigenschaft window.name beim Konfigurieren eines Dialogfelds in Ihrem Add-In nicht fest. Die window.name -Eigenschaft wird von diesen Outlook-Clients verwendet, um die Funktionalität über Seitenumleitungen hinweg beizubehalten.
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.

Eigenschaft	Verwendung
`AsyncResult.value`	Greift auf das Dialog-Objekt zu.
`AsyncResult.status`	Bestimmen Sie, ob der Vorgang erfolgreich war oder ein Fehler aufgetreten ist.
`AsyncResult.error`	Greifen Sie auf ein Error-Objekt zu, das nach einem fehlgeschlagenen Vorgang Fehlerinformationen bereitstellt.
`AsyncResult.asyncContext`	Greifen Sie auf Ihr benutzerdefiniertes Objekt oder Ihren Wert zu, wenn Sie eines als asyncContext-Parameter übergeben haben.

messageParent(message, messageOptions)

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

TypeScript

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

Parameter

message: string

Akzeptiert eine Nachricht aus dem Dialogfeld, die an das Add-In übermittelt wird. Alles, was in eine Zeichenfolge serialisiert werden kann, einschließlich JSON und XML, kann gesendet werden.

messageOptions: Office.DialogMessageOptions

Optional. Stellt Optionen zum Senden der Nachricht bereit.

Gibt zurück

void

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

TypeScript

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

openBrowserWindow(url)

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

TypeScript

openBrowserWindow(url: string): void;

Parameter

url: string

Die vollständige URL, die geöffnet werden soll, einschließlich Protokoll (http oder https) und Gegebenenfalls Portnummer. Andere Protokolle wie mailto werden nicht unterstützt.

Gibt zurück

void

Hinweise

Anforderungssatz: OpenBrowserWindowAPI 1.1

Beispiele

TypeScript

// 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();

Freigeben über

Office.UI interface

Hinweise

Beispiele

Methoden

Details zur Methode

addHandlerAsync(eventType, handler, options, callback)

Parameter

Gibt zurück

Hinweise

addHandlerAsync(eventType, handler, callback)

Parameter

Gibt zurück

Hinweise

Beispiele

closeContainer()

Gibt zurück

Hinweise

Beispiele

displayDialogAsync(startAddress, options, callback)

Parameter

Gibt zurück

Hinweise

Beispiele

displayDialogAsync(startAddress, callback)

Parameter

Gibt zurück

Hinweise

messageParent(message, messageOptions)

Parameter

Gibt zurück

Hinweise

Beispiele

openBrowserWindow(url)

Parameter

Gibt zurück

Hinweise

Beispiele

Zusätzliche Ressourcen