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

要求集：

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

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

要求集：

重要说明：

初始页必须与父页位于同一域中， (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

要求集：

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，包括协议 (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();

通过

Office.UI interface

注解

示例

方法

方法详细信息

addHandlerAsync(eventType, handler, options, callback)

参数

返回

注解

addHandlerAsync(eventType, handler, callback)

参数

返回

注解

示例

closeContainer()

返回

注解

示例

displayDialogAsync(startAddress, options, callback)

参数

返回

注解

示例

displayDialogAsync(startAddress, callback)

参数

返回

注解

messageParent(message, messageOptions)

参数

返回

注解

示例

openBrowserWindow(url)

参数

返回

注解

示例

其他资源