Office.Dialog interface
The object that is returned when UI.displayDialogAsync
is called. It exposes methods for registering event handlers and closing the dialog.
Remarks
Requirement set: DialogAPI
Methods
add |
Registers an event handler. The two supported events are:
|
close() | Called from a parent page to close the corresponding dialog box. This method is asynchronous. It does not take a callback parameter and it does not return a Promise object, so it cannot be awaited with either the |
message |
Delivers a message from the host page, such as a task pane or a UI-less function file, to a dialog that was opened from the page. |
send |
FOR INTERNAL USE ONLY. DO NOT CALL IN YOUR CODE. |
Method Details
addEventHandler(eventType, handler)
Registers an event handler. The two supported events are:
DialogMessageReceived. Triggered when the dialog box sends a message to its parent.
DialogEventReceived. Triggered when the dialog box has been closed or otherwise unloaded.
addEventHandler(eventType: Office.EventType, handler: (args: {message: string, origin: string | undefined} | {error: number}) => void): void;
Parameters
- eventType
- Office.EventType
Must be either DialogMessageReceived or DialogEventReceived.
- handler
-
(args: {message: string, origin: string | undefined} | {error: number}) => void
A function which accepts either an object with a message
and origin
property, if eventType
is DialogMessageReceived
, or an object with an error
property, if eventType
is DialogEventReceived
. Note that the origin
property is undefined
on clients that don’t support DialogOrigin 1.1.
Returns
void
Examples
// 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 and how to use that handler to close 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);
});
}
);
close()
Called from a parent page to close the corresponding dialog box.
This method is asynchronous. It does not take a callback parameter and it does not return a Promise object, so it cannot be awaited with either the await
keyword or the then
function. See this best practice for more information: Opening another dialog immediately after closing one
close(): void;
Returns
void
Examples
// 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 and how to use that handler to close 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);
});
}
);
messageChild(message, messageOptions)
Delivers a message from the host page, such as a task pane or a UI-less function file, to a dialog that was opened from the page.
messageChild(message: string, messageOptions?: DialogMessageOptions): void;
Parameters
- message
-
string
Accepts a message from the host page to deliver to the dialog. Anything that can be serialized to a string, including JSON and XML, can be sent.
- messageOptions
- Office.DialogMessageOptions
Optional. Provides options for how to send the message.
Returns
void
Remarks
Applications: Excel, Outlook (Minimum requirement set: Mailbox 1.9), PowerPoint, Word
Requirement sets:
If the
messageOptions
parameter is used, DialogOrigin 1.1 is also required.
Although classic Outlook on Mac doesn't support Mailbox 1.9, it does support DialogApi 1.2.
sendMessage(name)
FOR INTERNAL USE ONLY. DO NOT CALL IN YOUR CODE.
sendMessage(name: string): void;
Parameters
- name
-
string
Returns
void
Office Add-ins