Edit

Share via

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

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.

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();
            // Do something to process the message.
        });
    }
);

// 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();
            // Do something to process the message.
        });
    }
);

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

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:

Although classic Outlook on Mac doesn't support Mailbox 1.9, it does support DialogApi 1.2.

Examples

// The following example shows how to send information about the current active worksheet to the dialog.
await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    worksheet.load();
    await context.sync();
    worksheetPropertiesChanged(worksheet);
});

...

function worksheetPropertiesChanged(currentWorksheet) {
    const messageToDialog = JSON.stringify(currentWorksheet);
    dialog.messageChild(messageToDialog);
}

sendMessage(name)

FOR INTERNAL USE ONLY. DO NOT CALL IN YOUR CODE.

sendMessage(name: string): void;

Parameters

name

string

Returns

void