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 Word
要求集:
此方法的行为由以下项指定:
从无 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 的统一清单,请参阅 Office 外接程序和 Microsoft 365 的统一应用清单。
重要说明:
初始页必须与父页位于同一域中, (startAddress 参数) 。 初始网页加载后,你可以转到其他域。
任何调用
Office.context.ui.messageParent
的页面也必须与父页位于同一域中。若要了解 Office 对话 API 的规则、限制和最佳做法,请参阅 Office 对话 API 的最佳做法和规则。
有关错误以及如何处理错误的信息,请参阅 处理 Office 对话框中的错误和事件。
在 Outlook 网页版 和新的 Outlook on Windows 中,在外接程序中配置对话框时,不要设置 window.name 属性。 这些
window.name
Outlook 客户端使用 属性来维护跨页面重定向的功能。在传递给 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 的统一清单,请参阅 Office 外接程序和 Microsoft 365 的统一应用清单。
重要说明:
初始页必须与父页位于同一域中, (startAddress 参数) 。 初始网页加载后,你可以转到其他域。
任何调用
Office.context.ui.messageParent
的页面也必须与父页位于同一域中。若要了解 Office 对话 API 的规则、限制和最佳做法,请参阅 Office 对话 API 的最佳做法和规则。
有关错误以及如何处理错误的信息,请参阅 处理 Office 对话框中的错误和事件。
在 Outlook 网页版 和新的 Outlook on Windows 中,在外接程序中配置对话框时,不要设置 window.name 属性。 这些
window.name
Outlook 客户端使用 属性来维护跨页面重定向的功能。在传递给 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();