Office.Dialog interface

Package:

office

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

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.
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
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.
sendMessage(name)	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:

• DialogAPI 1.2

• Mailbox 1.9

• 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