Lidar com erros e eventos na caixa de diálogo do Office

Este artigo descreve como interceptar e manipular erros ao abrir a caixa de diálogo e erros que ocorrem dentro da caixa de diálogo.

Seu código deve lidar com duas categorias de eventos.

• Erros retornados pela chamada de porque a caixa de displayDialogAsync diálogo não pode ser criada.
• Erros e outros eventos na caixa de diálogo.

Erros de displayDialogAsync

Além dos erros gerais da plataforma e do sistema, quatro erros são específicos para chamar displayDialogAsync.

Quando displayDialogAsync é chamado, ele passa um objeto AsyncResult para sua função de retorno de chamada. Quando a chamada for bem-sucedida, a caixa de diálogo será aberta e a value propriedade do AsyncResult objeto será um objeto Dialog . Para obter um exemplo disso, consulte Enviar informações da caixa de diálogo para a página host. Quando a chamada para displayDialogAsync falha, a caixa de diálogo não é criada, a statusAsyncResult propriedade do objeto é definida como Office.AsyncResultStatus.Failede a error propriedade do objeto é preenchida. Você sempre deve fornecer um retorno de chamada que teste o e responda status quando for um erro. Para obter um exemplo que relata a mensagem de erro independentemente do número de código, consulte o código a seguir. (A showNotification função, não definida neste artigo, exibe ou registra o erro. Para obter um exemplo de como você pode implementar essa função em seu suplemento, consulte Exemplo de API de Caixa de Diálogo do Suplemento do 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);
    }
});

Erros e eventos na caixa de diálogo

Três erros e eventos na caixa de diálogo gerarão um DialogEventReceived evento na página do host. Para obter um lembrete do que é uma página host, consulte Abrir uma caixa de diálogo de uma página host.

Seu código pode atribuir um manipulador para o evento DialogEventReceived na chamada para displayDialogAsync. Apresentamos um exemplo simples a seguir.

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

Para obter um exemplo de um manipulador para o DialogEventReceived evento que cria mensagens de erro personalizadas para cada código de erro, consulte o exemplo a seguir.

function processDialogEvent(arg) {
    switch (arg.error) {
        case 12002:
            showNotification("The dialog box has been directed to a page that it can't 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;
    }
}

Confira também

Para ver um suplemento de exemplo que manipula erros dessa forma, confira Exemplo de API de Caixa de diálogo do Suplemento do Office.