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 });

方法

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

要求集:

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

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

要求集:

示例

// 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

注解

要求集: 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();