Обработка ошибок и событий в диалоговом окне Office

В этой статье описывается, как перехватывать и обрабатывать ошибки при открытии диалогового окна и ошибки, происходящие в диалоговом окне.

Примечание.

В этой статье предполагается, что вы знакомы с основами использования API диалога Office, как описано в разделе Использование API диалога Office в надстройках Office.

См. также рекомендации и правила для API диалога Office.

Код должен обрабатывать две категории событий.

• Ошибки, возвращаемые при вызове метода displayDialogAsync, так как не удается создать диалоговое окно.
• Ошибки и другие события в диалоговом окне.

Ошибки метода displayDialogAsync

Помимо общих ошибок платформы и системы, четыре ошибки относятся только к вызову displayDialogAsync.

Цифровой код	Значение
12004	Домен URL-адреса, переданного в, не является доверенным displayDialogAsync . Домен должен быть таким же, как и для главной страницы (а также протокол и номер порта).
12005	URL-адрес, передаваемый в метод displayDialogAsync, использует протокол HTTP. Необходим протокол HTTPS. (В некоторых версиях Office текст сообщения об ошибке, возвращаемый с 12005, совпадает с текстом, возвращенным для 12004.)
12007	Диалоговое окно уже открыто из этого главного окна. Для главного окна, например области задач, невозможно открыть сразу несколько диалоговых окон.
12009	Пользователь проигнорировал диалоговое окно. Эта ошибка может возникнуть в Office в Интернете, когда пользователи могут запретить надстройке представление диалогового окна. Дополнительные сведения см. в разделе Обработка блокировщиков всплывающих окон с помощью Office в Интернете.
12011	Надстройка работает в Office в Интернете, а конфигурация браузера пользователя блокирует всплывающие окна. Чаще всего это происходит, когда браузер имеет устаревшую версию Edge, а домен надстройки находится в другой зоне безопасности от домена, который пытается открыть диалоговое окно. Другой сценарий, который вызывает эту ошибку, заключается в том, что браузер является Safari и настроен для блокировки всех всплывающих окон. Рассмотрите возможность ответить на эту ошибку запросом на изменение конфигурации браузера или использовать другой браузер.

При displayDialogAsync вызове объект AsyncResult передается в функцию обратного вызова. При успешном вызове открывается диалоговое окно, а value свойство AsyncResult объекта — объект Dialog . Пример см. в разделе Отправка сведений из диалогового окна на ведущее окно. При сбое вызова displayDialogAsync диалоговое окно не создается, свойству statusAsyncResult объекта присваивается Office.AsyncResultStatus.Failedзначение , а error свойство объекта заполняется. Всегда следует предоставлять обратный вызов, который проверяет status и реагирует на ошибку. Пример сообщения об ошибке независимо от номера кода см. в следующем коде. (Функция showNotification , не определенная в этой статье, отображает или регистрирует ошибку. Пример реализации этой функции в надстройке см. в разделе Пример API диалогового окна надстроек Office.)

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	Одно из следующих: Не существует страницы по URL-адресу, переданного в displayDialogAsync. Страница, которая была передана displayDialogAsync загруженной, но диалоговое окно было перенаправлено на страницу, которую не удается найти или загрузить, или она была направлена на URL-адрес с недопустимым синтаксисом.
12003	Выполнена попытка открыть из диалогового окна страницу, для URL-адреса которой используется протокол HTTP. Необходим протокол HTTPS.
12006	Один из следующих продуктов: Диалоговое окно было закрыто, как правило, из-за того, что пользователь нажимал кнопку ЗакрытьX. Диалоговое окно вернуло заголовок ответа cross-Origin-Opener-Policy: same-origin . Чтобы избежать этого, необходимо задать для заголовка Cross-Origin-Opener-Policy: unsafe-none значение или настроить надстройку и диалоговое окно в том же домене, что и хост-страница.

Код может назначить обработчик для события 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.