Office.UI interface

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

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, options: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

参数

返回

注解

要求集： DialogAPI 1.2

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

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

addHandlerAsync(eventType: Office.EventType, handler: (result: DialogParentMessageReceivedEventArgs) => void, callback?: (result: AsyncResult<void>) => void): 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;
    }
}

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

closeContainer(): 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();

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

displayDialogAsync(startAddress: string, options?: DialogOptions, callback?: (result: AsyncResult<Dialog>) => void): 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 对话 API 的规则、限制和最佳做法，请参阅 Office 对话 API 的最佳做法和规则。

• 有关错误以及如何处理错误的信息，请参阅 处理 Office 对话框中的错误和事件。

• 在 Outlook 网页版 和新的 Outlook on Windows 中，在外接程序中配置对话框时，不要设置 window.name 属性。 这些 window.name Outlook 客户端使用 属性来维护跨页面重定向的功能。

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

示例

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

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

displayDialogAsync(startAddress: string, callback?: (result: AsyncResult<Dialog>) => void): 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 对话 API 的规则、限制和最佳做法，请参阅 Office 对话 API 的最佳做法和规则。

• 有关错误以及如何处理错误的信息，请参阅 处理 Office 对话框中的错误和事件。

• 在 Outlook 网页版 和新的 Outlook on Windows 中，在外接程序中配置对话框时，不要设置 window.name 属性。 这些 window.name Outlook 客户端使用 属性来维护跨页面重定向的功能。

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

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

messageParent(message: string, messageOptions?: 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));
}

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

openBrowserWindow(url: string): 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();