Office.Dialog interface

调用时 UI.displayDialogAsync 返回的对象。 它公开了用于注册事件处理程序和关闭对话框的方法。

注解

要求集: DialogApi

使用方

示例

// 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 and how to use that handler to close the dialog.

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();
            // Do something to process the message.
        });
    }
);

// 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();
            // Do something to process the message.
        });
    }
);

方法

addEventHandler(eventType, handler)

注册事件处理程序。 支持两种类型的事件:

  • DialogMessageReceived. 在对话框向其父级发送消息时触发。

  • DialogEventReceived。 在对话框已关闭或以其他方式卸载时触发。

close()

从父页调用以关闭相应的对话框。

此方法是异步的。 它不采用回调参数,也不返回 Promise 对象,因此无法使用关键字 (keyword) 或then函数来await等待它。 有关详细信息,请参阅此最佳实践: 关闭一个对话框后立即打开另一个对话框

messageChild(message, messageOptions)

将消息从主机页(例如任务窗格或无 UI 的函数文件)传递到从页面打开的对话框。

sendMessage(name)

仅供内部使用。 请勿调用代码。

方法详细信息

addEventHandler(eventType, handler)

注册事件处理程序。 支持两种类型的事件:

  • DialogMessageReceived. 在对话框向其父级发送消息时触发。

  • DialogEventReceived。 在对话框已关闭或以其他方式卸载时触发。

addEventHandler(eventType: Office.EventType, handler: (args: {message: string, origin: string | undefined} | {error: number}) => void): void;

参数

eventType
Office.EventType

必须是 DialogMessageReceived 或 DialogEventReceived。

handler

(args: {message: string, origin: string | undefined} | {error: number}) => void

一个函数,它接受具有 and message 属性的对象(如果 eventTypeDialogMessageReceived是)或具有属性error的对象(if eventType is DialogEventReceived)。origin 请注意,该 origin 属性位于 undefined 不支持 DialogOrigin 1.1 的客户端上。

返回

void

示例

// 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 and how to use that handler to close 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);
        });
    }
);

close()

从父页调用以关闭相应的对话框。

此方法是异步的。 它不采用回调参数,也不返回 Promise 对象,因此无法使用关键字 (keyword) 或then函数来await等待它。 有关详细信息,请参阅此最佳实践: 关闭一个对话框后立即打开另一个对话框

close(): void;

返回

void

示例

// 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 and how to use that handler to close 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);
        });
    }
);

messageChild(message, messageOptions)

将消息从主机页(例如任务窗格或无 UI 的函数文件)传递到从页面打开的对话框。

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

参数

message

string

接受来自主机页的消息以传递到对话框。 可以发送任何可以序列化为字符串的内容,包括 JSON 和 XML。

messageOptions
Office.DialogMessageOptions

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

返回

void

注解

应用程序:Excel、Outlook (最低要求集:Mailbox 1.9) 、PowerPoint Word

要求集:

尽管经典 Outlook on Mac 不支持邮箱 1.9,但它支持 DialogApi 1.2。

示例

// The following example shows how to send information about the current active worksheet to the dialog.
await Excel.run(async (context) => {
    const worksheet = context.workbook.worksheets.getActiveWorksheet();
    worksheet.load();
    await context.sync();
    worksheetPropertiesChanged(worksheet);
});

...

function worksheetPropertiesChanged(currentWorksheet) {
    const messageToDialog = JSON.stringify(currentWorksheet);
    dialog.messageChild(messageToDialog);
}

sendMessage(name)

仅供内部使用。 请勿调用代码。

sendMessage(name: string): void;

参数

name

string

返回

void