Office.UI interface

包:

office

提供可用于在 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 });

方法

addHandlerAsync(eventType, handler, options, callback)	使用指定的事件类型将事件处理程序添加到 对象。
addHandlerAsync(eventType, handler, callback)	使用指定的事件类型将事件处理程序添加到 对象。
closeContainer()	关闭正在执行 JavaScript 的 UI 容器。
displayDialogAsync(startAddress, options, callback)	显示一个对话框，用于显示或收集用户的信息，或者用于促进 Web 导航。
displayDialogAsync(startAddress, callback)	显示一个对话框，用于显示或收集用户的信息，或者用于促进 Web 导航。
messageParent(message, messageOptions)	将对话框中的消息传送到其父页/开始页。
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

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

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

要求集：

• DialogAPI

• Mailbox 1.5

此方法的行为由以下项指定：

• 从无 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

要求集：

• DialogAPI

• Mailbox 1.4

此方法在 Excel、PowerPoint 或 Word 加载项的 DialogApi 要求集中以及 Outlook 的邮箱要求集 1.4 中可用。 有关如何在清单中指定要求集的详细信息，请参阅 指定 Office 应用程序和 API 要求（如果使用仅外接程序清单）。 如果使用 Microsoft 365 的统一清单，请参阅 Office 外接程序和 Microsoft 365 的统一应用清单。

初始页必须与父页位于同一域中， (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	如果已将用户定义对象或值作为 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

要求集：

• DialogAPI

• Mailbox 1.4

此方法在 Excel、PowerPoint 或 Word 加载项的 DialogApi 要求集中以及 Outlook 的邮箱要求集 1.4 中可用。 有关如何在清单中指定要求集的详细信息，请参阅 指定 Office 应用程序和 API 要求（如果使用仅外接程序清单）。 如果使用 Microsoft 365 的统一清单，请参阅 Office 外接程序和 Microsoft 365 的统一应用清单。

初始页必须与父页位于同一域中， (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	如果已将用户定义对象或值作为 asyncContext 参数传递，则访问该对象或值。

messageParent(message, messageOptions)

将对话框中的消息传送到其父页/开始页。

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

参数

message

string

接受从对话框传送到外接程序的消息。 可以发送可序列化为字符串（包括 JSON 和 XML）的任何内容。

messageOptions

Office.DialogMessageOptions

可选。 提供有关如何发送邮件的选项。

返回

void

注解

应用程序：Excel、Outlook、PowerPoint Word

要求集：

• DialogAPI

• Mailbox 1.4

• 如果使用 参数 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，包括协议 (（例如 https) ）和端口号（如果有）。

返回

void

注解

要求集： OpenBrowserWindowAPI 1.1

示例

// 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();