处理 Office 对话框中的错误和事件

  • 项目

本文介绍如何捕获和处理打开对话框时出现的错误以及对话框中发生的错误。

注意

本文假定你已熟悉使用 Office 对话框 API 的基础知识，如在 Office 外接程序中使用 Office 对话 API 中所述。

另请参阅 Office 对话框 API 的最佳做法和规则。

代码应处理两类事件。

  • displayDialogAsync 调用返回的错误，因为无法创建对话框。
  • 对话框中的错误和其他事件。

DisplayDialogAsync 返回的错误

除了常规的平台和系统错误之外，还有四个特定于调用 displayDialogAsync的错误。

代码编号 含义
12004 传递给 displayDialogAsync 的 URL 的域不受信任。 此域必须与主机页的域相同（包括协议和端口号）。
12005 传递给 displayDialogAsync 的 URL 使用 HTTP 协议。 必须使用 HTTPS。 (在某些版本的 Office 中，使用 12005 返回的错误消息文本与 12004 返回的错误消息文本相同。)
12007 已从此主机窗口打开了一个对话框。 主机窗口（如任务窗格）一次只能打开一个对话框。
12009 用户已选择忽略对话框。 此错误可能发生在 Office web 版，其中用户可以选择不允许加载项显示对话框。 有关详细信息，请参阅使用Office web 版处理弹出窗口阻止程序。
12011 加载项在 Office web 版 中运行，并且用户的浏览器配置正在阻止弹出窗口。 当浏览器为 Edge 旧版且加载项的域与对话框尝试打开的域位于不同的安全区域时，最常发生这种情况。 触发此错误的另一种情况是，浏览器是 Safari，并且配置为阻止所有弹出窗口。 考虑通过提示用户更改其浏览器配置或使用其他浏览器来响应此错误。

调用 时 displayDialogAsync ，它将 AsyncResult 对象传递给其回调函数。 调用成功后，将打开对话框，并且 value 对象的 AsyncResult 属性是 Dialog 对象。 有关此示例，请参阅 将信息从对话框发送到主机页。 对 的调用 displayDialogAsync 失败时，不会创建对话框， status 对象的 AsyncResult 属性设置为 Office.AsyncResultStatus.Failed，并 error 填充对象的 属性。 应始终提供一个回调，用于测试 status 并在出错时做出响应。 有关报告错误消息而不考虑其代码号的示例，请参阅以下代码。 showNotification (本文中未定义的 函数显示或记录错误。有关如何在外接程序中实现此函数的示例，请参阅 Office 外接程序对话框 API 示例。) 

let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
function (asyncResult) {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        showNotification(asyncResult.error.code = ": " + asyncResult.error.message);
    } else {
        dialog = asyncResult.value;
        dialog.addEventHandler(Office.EventType.DialogMessageReceived, processMessage);
    }
});

对话框中的错误和事件

对话框中的三个错误和事件将在主机页中引发事件 DialogEventReceived 。 有关主机页的提醒，请参阅 从主机页打开对话框。

代码编号 含义
12002 下列一种含义：
- 传递给 displayDialogAsync 的 URL 没有对应的页面。
- 传递给 displayDialogAsync 加载的页面，但对话框随后被重定向到它找不到或加载的页面，或者它已被定向到语法无效的 URL。
12003 对话框定向到使用 HTTP 协议的 URL。 必须使用 HTTPS。
12006 对话框已关闭，通常是因为用户选择了 “关闭 ”按钮 X。

代码可以在调用 DialogEventReceived 时为 displayDialogAsync 事件分配处理程序。 下面展示了一个非常简单的示例。

let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
    function (result) {
        dialog = result.value;
        dialog.addEventHandler(Office.EventType.DialogEventReceived, processDialogEvent);
    }
);

有关为每个错误代码创建自定义错误消息的事件的处理程序 DialogEventReceived 示例，请参阅以下示例。

function processDialogEvent(arg) {
    switch (arg.error) {
        case 12002:
            showNotification("The dialog box has been directed to a page that it cannot find or load, or the URL syntax is invalid.");
            break;
        case 12003:
            showNotification("The dialog box has been directed to a URL with the HTTP protocol. HTTPS is required.");            break;
        case 12006:
            showNotification("Dialog closed.");
            break;
        default:
            showNotification("Unknown error in dialog box.");
            break;
    }
}

另请参阅

有关这样处理错误的样本加载项，请参阅 Office 加载项 Dialog API 示例。