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

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler to the object using the specified event type.

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.

displayDialogAsync(startAddress, callback)

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

messageParent(message, messageOptions)

Delivers a message from the dialog box to its parent/opener page.

openBrowserWindow(url)

Opens a browser window and loads the specified URL.

Method Details

addHandlerAsync(eventType, handler, options, callback)

Adds an event handler to the object using the specified event type.

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Parameters

eventType
Office.EventType

Specifies the type of event to add. This must be Office.EventType.DialogParentMessageReceived.

handler

(result: Office.DialogParentMessageReceivedEventArgs) => void

The event handler function to add, whose only parameter is of type Office.DialogParentMessageReceivedEventArgs.

options
Office.AsyncContextOptions

Optional. Provides an option for preserving context data of any type, unchanged, for use in a callback.

callback

(result: Office.AsyncResult<void>) => void

Optional. A function that is invoked when the handler registration returns, whose only parameter is of type Office.AsyncResult.

Returns

void

Remarks

Requirement set: DialogAPI 1.2

You can add multiple event handlers for the specified event type as long as the name of each event handler function is unique.

closeContainer()

Closes the UI container where the JavaScript is executing.

closeContainer(): void;

Returns

void

Remarks

Hosts: Excel, Outlook (Minimum requirement set: Mailbox 1.5), PowerPoint, Word

Requirement sets:

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 task pane: The task pane will close. Any dialog opened by displayDialogAsync will also close. If the task pane 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 full HTTPS URL that opens in the dialog. Relative URLs must not be used.

options
Office.DialogOptions

Optional. Accepts an Office.DialogOptions object to define dialog display.

callback

(result: Office.AsyncResult<Office.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

Hosts: Excel, Outlook, PowerPoint, Word

Requirement sets:

This method is available in the DialogApi requirement set for Excel, PowerPoint, or Word 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.

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 `AppDomains` 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.
12009 The user chose to ignore the dialog box. This error can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.

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.

displayDialogAsync(startAddress, callback)

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

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

Parameters

startAddress

string

Accepts the initial full HTTPS URL that opens in the dialog. Relative URLs must not be used.

callback

(result: Office.AsyncResult<Office.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

Hosts: Excel, Outlook, PowerPoint, Word

Requirement sets:

This method is available in the DialogApi requirement set for Excel, PowerPoint, or Word 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.

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 `AppDomains` 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.
12009 The user chose to ignore the dialog box. This error can occur in online versions of Office, where users may choose not to allow an add-in to present a dialog.

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(message, messageOptions)

Delivers a message from the dialog box to its parent/opener page.

messageParent(message: string, messageOptions?: DialogMessageOptions): void;

Parameters

message

string

Accepts a message from the dialog to deliver to the add-in. Anything that can 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

Requirement sets:

openBrowserWindow(url)

Opens a browser window and loads the specified URL.

openBrowserWindow(url: string): void;

Parameters

url

string

The full URL to be opened including protocol (e.g., https), and port number, if any.

Returns

void

Remarks

Requirement set: OpenBrowserWindowAPI 1.1