Office.UI interface
Stellt Objekte und Methoden bereit, mit denen Sie Benutzeroberflächenkomponenten wie Dialogfelder in Ihren Office-Add-Ins erstellen und bearbeiten können.
Weitere Informationen finden Sie unter Verwenden der Dialog-API in Ihren Office-Add-Ins.
Hinweise
Beispiele
// 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
| add |
Fügt dem -Objekt unter Verwendung des angegebenen Ereignistyps einen Ereignishandler hinzu. |
| add |
Fügt dem -Objekt unter Verwendung des angegebenen Ereignistyps einen Ereignishandler hinzu. |
| close |
Schließt den UI-Container, in dem der JavaScript-Code ausgeführt wird. |
| display |
Zeigt ein Dialogfeld an, um Informationen vom Benutzer anzuzeigen oder zu sammeln oder um die Webnavigation zu erleichtern. |
| display |
Zeigt ein Dialogfeld an, um Informationen vom Benutzer anzuzeigen oder zu sammeln oder um die Webnavigation zu erleichtern. |
| message |
Übermittelt eine Nachricht vom Dialogfeld an die übergeordnete/öffnende Seite. |
| open |
Ö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.
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.
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
// 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.
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
// 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.
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.
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
| Codenummer | Bedeutung |
|---|---|
| 12004 | Die Domäne der URL, die an displayDialogAsync übergeben wird, ist nicht vertrauenswürdig. Die Domäne muss entweder dieselbe Domäne wie die Hostseite sein (einschließlich Protokoll und Portnummer), oder sie muss im AppDomains Abschnitt des Add-In-Manifests registriert sein. |
| 12005 | Die an displayDialogAsync übergebene URL verwendet das HTTP-Protokoll. HTTPS ist erforderlich. (In manchen Versionen von Office ist die Fehlermeldung, die für 12005 zurückgegeben wird, dieselbe wie für 12004.) |
| 12007 | Ein Dialogfeld ist bereits im Aufgabenbereich geöffnet. Für ein Aufgabenbereich-Add-In kann nur ein Dialogfeld geöffnet sein. |
| 12009 | Der Benutzer hat das Dialogfeld ignoriert. Dieser Fehler kann in Online-Versionen von Office auftreten, in denen Benutzer auswählen können, dass ein Add-In kein Dialogfeld präsentiert. |
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
// 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.
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:
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
| Codenummer | Bedeutung |
|---|---|
| 12004 | Die Domäne der URL, die an displayDialogAsync übergeben wird, ist nicht vertrauenswürdig. Die Domäne muss entweder dieselbe Domäne wie die Hostseite sein (einschließlich Protokoll und Portnummer), oder sie muss im AppDomains Abschnitt des Add-In-Manifests registriert sein. |
| 12005 | Die an displayDialogAsync übergebene URL verwendet das HTTP-Protokoll. HTTPS ist erforderlich. (In manchen Versionen von Office ist die Fehlermeldung, die für 12005 zurückgegeben wird, dieselbe wie für 12004.) |
| 12007 | Ein Dialogfeld ist bereits im Aufgabenbereich geöffnet. Für ein Aufgabenbereich-Add-In kann nur ein Dialogfeld geöffnet sein. |
| 12009 | Der Benutzer hat das Dialogfeld ignoriert. Dieser Fehler kann in Online-Versionen von Office auftreten, in denen Benutzer auswählen können, dass ein Add-In kein Dialogfeld präsentiert. |
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.
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:
Wenn der
messageOptionsParameter 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));
}
openBrowserWindow(url)
Öffnet ein Browserfenster und lädt die angegebene URL.
openBrowserWindow(url: string): void;Parameter
- url
-
string
Die vollständige URL, die geöffnet werden soll, einschließlich Protokoll (z. B. HTTPS) und Gegebenenfalls Portnummer.
Gibt zurück
void
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();
Office Add-ins