Office.Dialog interface
调用 时 UI.displayDialogAsync 返回的对象。 它公开用于注册事件处理程序和关闭对话框的方法。
注解
要求集： DialogAPI
方法
| add |
注册事件处理程序。 支持两种类型的事件：
|
| close() | 从父页调用以关闭相应的对话框。 此方法是异步的。 它不采用回调参数，并且不返回 Promise 对象，因此不能使用 |
| message |
将消息从主机页面（如任务窗格或无 UI 函数文件）传递到从页面打开的对话框。 |
| send |
仅供内部使用。 不要在代码中调用 。 |
方法详细信息
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
一个函数，它接受具有 message 和 属性的对象（如果 eventType 为DialogMessageReceived ），或者接受具有 error 属性的对象（如果 eventType 为 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 对象，因此不能使用 await 关键字 (keyword) 或 then 函数等待它。 有关详细信息，请参阅此最佳做法： 关闭一个对话框后立即打开另一个对话框
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
要求集：
如果使用 参数
messageOptions，则还需要 DialogOrigin 1.1 。
尽管经典 Outlook on Mac 不支持 Mailbox 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