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
| add |
Adds an event handler to the object using the specified event type. |
| add |
Adds an event handler to the object using the specified event type. |
| close |
Closes the UI container where the JavaScript is executing. |
| display |
Displays a dialog to show or collect information from the user or to facilitate Web navigation. |
| display |
Displays a dialog to show or collect information from the user or to facilitate Web navigation. |
| message |
Delivers a message from the dialog box to its parent/opener page. |
| open |
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
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.
addHandlerAsync(eventType, handler, callback)
Adds an event handler to the object using the specified event type.
addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, 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.
- 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.
Examples
// The following example shows how to add an event handler for the DialogParentMessageReceived event.
Office.onReady(() => {
Office.context.ui.addHandlerAsync(
Office.EventType.DialogParentMessageReceived,
onMessageFromParent,
onRegisterMessageComplete
);
});
function onMessageFromParent(arg) {
const messageFromParent = JSON.parse(arg.message);
document.querySelector('h1').textContent = messageFromParent.name;
}
function onRegisterMessageComplete(asyncResult) {
if (asyncResult.status === Office.AsyncResultStatus.Failed) {
console.log(asyncResult.error.message);
return;
}
}
closeContainer()
Closes the UI container where the JavaScript is executing.
closeContainer(): void;Returns
void
Remarks
Applications: 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 function to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object.
Returns
void
Remarks
Applications: 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 applications and API requirements, if you're using the XML manifest. If you're using the Teams manifest (preview), see Teams manifest for Office Add-ins (preview).
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 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 |
|---|---|
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 |
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. 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);
});
}
);
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 function to handle the dialog creation attempt. If successful, the AsyncResult.value is a Dialog object.
Returns
void
Remarks
Applications: 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 applications and API requirements, if you're using the XML manifest. If you're using the Teams manifest (preview), see Teams manifest for Office Add-ins (preview).
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 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 |
|---|---|
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:
If the
messageOptionsparameter is used, DialogOrigin 1.1 is also required.
Examples
// The following example shows how to send a JSON string to the parent. The profile object
// is returned from some website when a user signs into it.
function userProfileSignedIn(profile) {
const profileMessage = {
"name": profile.name,
"email": profile.email,
};
Office.context.ui.messageParent(JSON.stringify(profileMessage));
}
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
Office Add-ins
Feedback
Coming soon: Throughout 2024 we will be phasing out GitHub Issues as the feedback mechanism for content and replacing it with a new feedback system. For more information see: https://aka.ms/ContentUserFeedback.
Submit and view feedback for