Office.UI interface

提供可用于在 Office 外接程序中创建和操作 UI 组件(如对话框)的对象和方法。

访问" 在 Office 加载项中使用对话框 API有关详细信息,请参阅 。

方法

addHandlerAsync(eventType, handler, options, callback)

使用指定的事件类型向对象添加事件处理程序。

closeContainer()

关闭正在执行 JavaScript 的 UI 容器。

displayDialogAsync(startAddress, options, callback)

显示一个对话框,以显示或收集用户的信息或促进 Web 导航。

displayDialogAsync(startAddress, callback)

显示一个对话框,以显示或收集用户的信息或促进 Web 导航。

messageParent(message)

将对话框中的消息传送到其父页/开始页。调用此 API 的页必须与父页位于相同的域。

openBrowserWindow(url)

打开浏览器窗口并加载指定的 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

只要每个事件处理程序函数的名称是唯一的,就可以为指定的事件类型添加多个事件处理程序。

closeContainer()

关闭正在执行 JavaScript 的 UI 容器。

closeContainer(): void;

返回

void

注解

主机:Excel、Outlook (最低要求集:Mailbox 1.5) 、PowerPoint、Word

要求集

此方法的行为由以下内容指定:

  • 从无 UI 命令按钮调用:不起作用。 displayDialogAsync 打开的任何对话框将保持打开状态。

  • 从任务窗格调用:任务窗格将关闭。 由 displayDialogAsync 打开的任何对话框也将关闭。 如果任务窗格支持固定并且由用户固定,它将取消固定。

  • 从模块扩展调用:不起作用。

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

可选。 接受用于处理对话框创建尝试的 callback 方法。 如果成功,则 AsyncResult.value 为 Dialog 对象。

返回

void

注解

主机:Excel、Outlook、PowerPoint、Word

要求集

此方法在 Excel、PowerPoint 或 Word 外接程序的 DialogApi 要求集以及 Outlook 的邮箱要求集 1.4 中可用。 若要详细了解如何在清单中指定要求集,请参阅指定 Office 主机 和 API 要求.

初始页面必须与 startAddress 参数参数 (位于同一域中) 。 初始网页加载后,你可以转到其他域。

任何页面 Office.context.ui.messageParent 调用也必须位于与父页面相同的域中。

设计注意事项

下列设计注意事项适用于对话框:

  • Office 加载项任务窗格随时只能打开一个对话框。 可以从外接程序命令中同时打开多个对话框, (自定义功能区按钮或菜单项) 。

  • 用户可以移动每个对话框和调整其大小。

  • 每个对话框在打开时都在屏幕上居中显示。

  • 对话框按照创建的顺序出现在主机应用程序顶部。

使用对话框可以执行以下操作:

  • 显示身份验证页以收集用户凭据。

  • 显示 ShowTaskpane 或 ExecuteAction 命令中的错误/进度/输入屏幕。

  • 临时增加用户可用于完成一项任务的表面区域。

不要使用对话框与文档进行交互。而是使用任务窗格。

displayDialogAsync 错误

代码编号 含义
12004 传递给 displayDialogAsync 的 URL 的域不可信。 该域必须与主机页(包括协议和端口号)具有同一域,或必须在外接程序清单的 `AppDomains` 部分中注册。
12005 传递给 displayDialogAsync 的 URL 使用 HTTP 协议。 必须使用 HTTPS。 (在 Office 的某些版本中,返回 12005 的错误消息与返回 12004 错误消息是相同的。)
12007 从任务窗格已经打开了一个对话框。任务窗格外接程序一次只能打开一个对话框。
12009 用户已选择忽略对话框。 联机版本的 Office 中可能会发生此错误,用户可能会选择不允许加载项显示对话框。

在传递给 displayDialogAsync 方法的回调函数中,您可以使用 AsyncResult 对象的属性返回以下信息。

属性 用于
AsyncResult.value 访问 Dialog 对象。
AsyncResult.status 确定操作是成功还是失败。
AsyncResult.error 如果操作失败,则访问提供错误信息的 Error 对象。
AsyncResult.asyncContext 如果您将用户定义的一个 object 或值作为 asyncContext 参数传递,则对其进行访问。

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

可选。 接受用于处理对话框创建尝试的 callback 方法。 如果成功,则 AsyncResult.value 为 Dialog 对象。

返回

void

注解

主机:Excel、Outlook、PowerPoint、Word

要求集

此方法在 Excel、PowerPoint 或 Word 外接程序的 DialogApi 要求集以及 Outlook 的邮箱要求集 1.4 中可用。 若要详细了解如何在清单中指定要求集,请参阅指定 Office 主机 和 API 要求.

初始页面必须与 startAddress 参数参数 (位于同一域中) 。 初始网页加载后,你可以转到其他域。

任何页面 Office.context.ui.messageParent 调用也必须位于与父页面相同的域中。

设计注意事项

下列设计注意事项适用于对话框:

  • Office 加载项任务窗格随时只能打开一个对话框。 可以从外接程序命令中同时打开多个对话框, (自定义功能区按钮或菜单项) 。

  • 用户可以移动每个对话框和调整其大小。

  • 每个对话框在打开时都在屏幕上居中显示。

  • 对话框按照创建的顺序出现在主机应用程序顶部。

使用对话框可以执行以下操作:

  • 显示身份验证页以收集用户凭据。

  • 显示 ShowTaskpane 或 ExecuteAction 命令中的错误/进度/输入屏幕。

  • 临时增加用户可用于完成一项任务的表面区域。

不要使用对话框与文档进行交互。而是使用任务窗格。

displayDialogAsync 错误

代码编号 含义
12004 传递给 displayDialogAsync 的 URL 的域不可信。 该域必须与主机页(包括协议和端口号)具有同一域,或必须在外接程序清单的 `AppDomains` 部分中注册。
12005 传递给 displayDialogAsync 的 URL 使用 HTTP 协议。 必须使用 HTTPS。 (在 Office 的某些版本中,返回 12005 的错误消息与返回 12004 错误消息是相同的。)
12007 从任务窗格已经打开了一个对话框。任务窗格外接程序一次只能打开一个对话框。
12009 用户已选择忽略对话框。 联机版本的 Office 中可能会发生此错误,用户可能会选择不允许加载项显示对话框。

在传递给 displayDialogAsync 方法的回调函数中,您可以使用 AsyncResult 对象的属性返回以下信息。

属性 用于
AsyncResult.value 访问 Dialog 对象。
AsyncResult.status 确定操作是成功还是失败。
AsyncResult.error 如果操作失败,则访问提供错误信息的 Error 对象。
AsyncResult.asyncContext 如果您将用户定义的一个 object 或值作为 asyncContext 参数传递,则对其进行访问。

messageParent(message)

将对话框中的消息传送到其父页/开始页。调用此 API 的页必须与父页位于相同的域。

messageParent(message: boolean | string): void;

参数

message

boolean | string

接受从对话框传送到外接程序的消息。 除了布尔值之外,还可以发送任何可序列化为字符串(包括 JSON 和 XML)的项。

返回

void

注解

要求集 :DialogAPI

openBrowserWindow(url)

打开浏览器窗口并加载指定的 URL。

openBrowserWindow(url: string): void;

参数

url

string

要打开的完整 URL,包括协议 (,例如 https) 和端口号(如果有)。

返回

void

注解

要求集 :OpenBrowserWindowAPI 1.1