Office.UI interface

Provides objects and methods that you can use to create and manipulate UI components, such as dialog boxes, in your Office Add-ins.

Visit "Use the Dialog API in your Office Add-ins" for more information.

Methods

closeContainer()

Closes the UI container where the JavaScript is executing.

displayDialogAsync(startAddress, options, callback)

Displays a dialog to show or collect information from the user or to facilitate Web navigation.

messageParent(messageObject)

Delivers a message from the dialog box to its parent/opener page. The page calling this API must be on the same domain as the parent.

Method Details

closeContainer()

Closes the UI container where the JavaScript is executing.

closeContainer(): void;
Returns
void
Remarks
HostsExcel, Word, PowerPoint, Outlook (Minimum requirement set: Mailbox 1.5)

The behavior of this method is specified by the following:

  • Called from a UI-less command button: No effect. Any dialog opened by displayDialogAsync will remain open.

  • Called from a taskpane: The taskpane will close. Any dialog opened by displayDialogAsync will also close. If the taskpane supports pinning and was pinned by the user, it will be un-pinned.

  • Called from a module extension: No effect.

displayDialogAsync(startAddress, options, callback)

Displays a dialog to show or collect information from the user or to facilitate Web navigation.

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;
Parameters
startAddress
string

Accepts the initial HTTPS URL that opens in the dialog.

options
Office.DialogOptions

Optional. Accepts anOffice.DialogOptions object to define dialog display.

callback
(result: AsyncResult<Dialog>) => void

Optional. Accepts a callback method to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object.

Returns
void
Remarks
HostsWord, Excel, Outlook, PowerPoint
Requirement setsDialogAPI, Mailbox 1.4

This method is available in the DialogApi requirement set for Word, Excel, or PowerPoint add-ins, and in the Mailbox requirement set 1.4 for Outlook. For more on how to specify a requirement set in your manifest, see Specify Office hosts and API requirements.

The initial page must be on the same domain as the parent page (the startAddress parameter). After the initial page loads, you can go to other domains.

Any page calling office.context.ui.messageParent must also be on the same domain as the parent page.

Design considerations:

The following design considerations apply to dialog boxes:

  • An Office Add-in task pane can have only one dialog box open at any time. Multiple dialogs can be open at the same time from Add-in Commands (custom ribbon buttons or menu items).

  • Every dialog box can be moved and resized by the user.

  • Every dialog box is centered on the screen when opened.

  • Dialog boxes appear on top of the host application and in the order in which they were created.

Use a dialog box to:

  • Display authentication pages to collect user credentials.

  • Display an error/progress/input screen from a ShowTaskpane or ExecuteAction command.

  • Temporarily increase the surface area that a user has available to complete a task.

Do not use a dialog box to interact with a document. Use a task pane instead.

For a design pattern that you can use to create a dialog box, see Client Dialog in the Office Add-in UX Design Patterns repository on GitHub.

displayDialogAsync Errors:

Code number Meaning
12004 The domain of the URL passed to displayDialogAsync is not trusted. The domain must be either the same domain as the host page (including protocol and port number), or it must be registered in the section of the add-in manifest.
12005 The URL passed to displayDialogAsync uses the HTTP protocol. HTTPS is required. (In some versions of Office, the error message returned with 12005 is the same one returned for 12004.)
12007 A dialog box is already opened from the task pane. A task pane add-in can only have one dialog box open at a time.

In the callback function passed to the displayDialogAsync method, you can use the properties of the AsyncResult object to return the following information.

Property Use to
AsyncResult.value Access the Dialog object.
AsyncResult.status Determine the success or failure of the operation.
AsyncResult.error Access an Error object that provides error information if the operation failed.
AsyncResult.asyncContext Access your user-defined object or value, if you passed one as the asyncContext parameter.

messageParent(messageObject)

Delivers a message from the dialog box to its parent/opener page. The page calling this API must be on the same domain as the parent.

messageParent(messageObject: any): void;
Parameters
messageObject
any

Accepts a message from the dialog to deliver to the add-in.

Returns
void