Office.UI interface
提供对象和方法,用于在 Office 加载项中创建和操作 UI 组件(如对话框)。
有关如何配置对话框的指南,请参阅 在 Office 加载项中使用对话框 API。
注解
使用方
示例
// Get an Office.UI object and use it to open a dialog with a specified size.
const uiContext = Office.context.ui;
uiContext.displayDialogAsync("https://www.contoso.com/myDialog.html", { height: 30, width: 20 });
方法
| add |
使用指定的事件类型将事件处理程序添加到对象。 |
| add |
使用指定的事件类型将事件处理程序添加到对象。 |
| close |
关闭正在执行 JavaScript 的 UI 容器。 |
| display |
显示对话框以显示或收集来自用户的信息,或帮助 Web 导航。 |
| display |
显示对话框以显示或收集来自用户的信息,或帮助 Web 导航。 |
| message |
将对话框中的消息传送到其父页/开始页。 |
| open |
打开浏览器窗口并加载指定的 URL。 |
方法详细信息
addHandlerAsync(eventType, handler, options, callback)
使用指定的事件类型将事件处理程序添加到对象。
addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;
参数
- eventType
- Office.EventType
指定要添加事件的类型。 这必须是 Office.EventType.DialogParentMessageReceived。
- handler
-
(result: Office.DialogParentMessageReceivedEventArgs) => void
要添加的事件处理程序函数,其唯一参数的类型为 Office.DialogParentMessageReceivedEventArgs。
- options
- Office.AsyncContextOptions
提供用于保留任何类型的上下文数据(不变)以供回调使用的选项。
- callback
-
(result: Office.AsyncResult<void>) => void
可选。 处理程序注册返回时调用的函数,其唯一参数的类型为 Office.AsyncResult。
返回
void
注解
要求集: DialogApi 1.2
只要每个事件处理程序函数的名称唯一,就可以为指定的事件类型添加多个事件处理程序。
addHandlerAsync(eventType, handler, callback)
使用指定的事件类型将事件处理程序添加到对象。
addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): void;
参数
- eventType
- Office.EventType
指定要添加事件的类型。 这必须是 Office.EventType.DialogParentMessageReceived。
- handler
-
(result: Office.DialogParentMessageReceivedEventArgs) => void
要添加的事件处理程序函数,其唯一参数的类型为 Office.DialogParentMessageReceivedEventArgs。
- callback
-
(result: Office.AsyncResult<void>) => void
可选。 处理程序注册返回时调用的函数,其唯一参数的类型为 Office.AsyncResult。
返回
void
注解
要求集: DialogApi 1.2
只要每个事件处理程序函数的名称唯一,就可以为指定的事件类型添加多个事件处理程序。
示例
// 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()
关闭正在执行 JavaScript 的 UI 容器。
closeContainer(): void;
返回
void
注解
应用程序:Excel、Outlook (最低要求集:Mailbox 1.5) 、PowerPoint
要求集:
此方法的行为由以下内容指定:
从无 UI 命令按钮调用:无效果。 displayDialogAsync 打开的任何对话框将保持打开状态。
从任务窗格调用:将关闭任务窗格。 displayDialogAsync 打开的任何对话框也将关闭。 如果任务窗格支持固定并由用户固定,则将取消固定。
从模块扩展调用:无效果。
示例
// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();
displayDialogAsync(startAddress, options, callback)
显示对话框以显示或收集来自用户的信息,或帮助 Web 导航。
displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): void;
参数
- startAddress
-
string
接受在对话框中打开的初始完整 HTTPS URL。 不得使用相对 URL。
- options
- Office.DialogOptions
可选。 接受 Office.DialogOptions 对象来定义对话框显示。
- callback
-
(result: Office.AsyncResult<Office.Dialog>) => void
可选。 接受回调函数以处理对话框创建尝试。 如果成功,AsyncResult.value 则为 Dialog 对象。
返回
void
注解
应用程序: Excel、Outlook、PowerPoint、Word
要求集:
Excel、PowerPoint 或 Word 加载项的 DialogApi 要求集以及 Outlook 的邮箱要求集 1.4 中提供此方法。 有关如何在清单中指定要求集的详细信息,如果使用的是仅加载项清单,请参阅 指定 Office 应用程序和 API 要求。 如果使用 Microsoft 365 统一清单,请参阅 具有 Microsoft 365 统一应用清单的 Office 加载项。
重要说明:
初始页必须与父页位于同一域上, (startAddress 参数) 。 初始网页加载后,你可以转到其他域。
任何页面调用
Office.context.ui.messageParent也必须与父页面位于同一域上。若要了解 Office 对话框 API 的规则、限制和最佳做法,请参阅 Office 对话框 API 的最佳做法和规则。
有关错误及其处理方式的信息,请参阅 “处理 Office 中的错误和事件”对话框。
在 Windows 上的 Outlook 网页版 和新版 Outlook 中,在加载项中配置对话框时请勿设置 window.name 属性。 这些 Outlook 客户端使用该
window.name属性来维护跨页面重定向的功能。在传递给 displayDialogAsync 方法的回调函数中,您可以使用 AsyncResult 对象的属性返回以下信息。
| 属性 | 用途 |
|---|---|
AsyncResult.value | 访问 Dialog 对象。 |
AsyncResult.status | 确定操作是成功还是失败。 |
AsyncResult.error | 如果操作失败,则访问提供错误信息的 Error 对象。 |
AsyncResult.asyncContext | 访问用户定义的对象或值(如果您将一个对象或值作为 asyncContext 参数传递)。 |
示例
// 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)
显示对话框以显示或收集来自用户的信息,或帮助 Web 导航。
displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): void;
参数
- startAddress
-
string
接受在对话框中打开的初始完整 HTTPS URL。 不得使用相对 URL。
- callback
-
(result: Office.AsyncResult<Office.Dialog>) => void
可选。 接受回调函数以处理对话框创建尝试。 如果成功,AsyncResult.value 则为 Dialog 对象。
返回
void
注解
应用程序: Excel、Outlook、PowerPoint、Word
要求集:
Excel、PowerPoint 或 Word 加载项的 DialogApi 要求集以及 Outlook 的邮箱要求集 1.4 中提供此方法。 有关如何在清单中指定要求集的详细信息,如果使用的是仅加载项清单,请参阅 指定 Office 应用程序和 API 要求。 如果使用 Microsoft 365 统一清单,请参阅 具有 Microsoft 365 统一应用清单的 Office 加载项。
重要说明:
初始页必须与父页位于同一域上, (startAddress 参数) 。 初始网页加载后,你可以转到其他域。
任何页面调用
Office.context.ui.messageParent也必须与父页面位于同一域上。若要了解 Office 对话框 API 的规则、限制和最佳做法,请参阅 Office 对话框 API 的最佳做法和规则。
有关错误及其处理方式的信息,请参阅 “处理 Office 中的错误和事件”对话框。
在 Windows 上的 Outlook 网页版 和新版 Outlook 中,在加载项中配置对话框时请勿设置 window.name 属性。 这些 Outlook 客户端使用该
window.name属性来维护跨页面重定向的功能。在传递给 displayDialogAsync 方法的回调函数中,您可以使用 AsyncResult 对象的属性返回以下信息。
| 属性 | 用途 |
|---|---|
AsyncResult.value | 访问 Dialog 对象。 |
AsyncResult.status | 确定操作是成功还是失败。 |
AsyncResult.error | 如果操作失败,则访问提供错误信息的 Error 对象。 |
AsyncResult.asyncContext | 访问用户定义的对象或值(如果您将一个对象或值作为 asyncContext 参数传递)。 |
messageParent(message, messageOptions)
将对话框中的消息传送到其父页/开始页。
messageParent(message: string, messageOptions?: DialogMessageOptions): void;
参数
- message
-
string
接受从对话框传送到外接程序的消息。 可以发送任何可以序列化为字符串(包括 JSON 和 XML)的内容。
- messageOptions
- Office.DialogMessageOptions
可选。 提供有关如何发送邮件的选项。
返回
void
注解
应用程序: Excel、Outlook、PowerPoint、Word
要求集:
如果使用该
messageOptions参数,则还需要 DialogOrigin 1.1 。
示例
// 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)
打开浏览器窗口并加载指定的 URL。
openBrowserWindow(url: string): void;
参数
- url
-
string
要打开的完整 URL,包括协议 (http 或 https) 以及端口号(如果有)。 不支持 mailto 等其他协议。
返回
void
注解
示例
// The following example shows how to open a browser window to a download page and then close the add-in task pane.
Office.context.ui.openBrowserWindow("https://www.contoso.com/download");
Office.context.ui.closeContainer();