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
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
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.
sendMessage(name)
FOR INTERNAL USE ONLY. DO NOT CALL IN YOUR CODE.
sendMessage(name: string): void;
Parameters
- name
-
string
Returns
void
Feedback
Submit and view feedback for