Manipular erros e eventos na caixa de diálogo do Office

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

Observação

Este artigo presupõe que você esteja familiarizado com os conceitos básicos de usar a API de diálogo do Office, conforme descrito em Usar a API de diálogo do Office em seus Suplementos do Office.

Consulte também Práticas recomendadas e regras para a API de diálogo do Office.

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

• Erros retornados pela chamada de displayDialogAsync porque não foi possível criar a caixa de diálogo.
• 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.

Número do código	Significado
12004	O domínio que a URL transmitiu para displayDialogAsync não é confiável. O domínio deve ser o mesmo domínio que o da página de host (incluindo o protocolo e o número de porta).
12005	A URL passada para displayDialogAsync usa o protocolo HTTP. HTTPS é necessário. (Em algumas versões do Office, o texto da mensagem de erro retornado com 12005 é o mesmo retornado para 12004.)
12007	Uma caixa de diálogo já está aberta na janela do host. Uma janela do host, como um painel de tarefas, só pode ter uma caixa de diálogo aberta por vez.
12009	O usuário opta por ignorar a caixa de diálogo. Esse erro pode ocorrer em Office na Web, em que os usuários podem optar por não permitir que um suplemento apresente uma caixa de diálogo. Para obter mais informações, consulte Manipulando bloqueadores pop-up com Office na Web.
12011	O suplemento está em execução no Office na Web e a configuração do navegador do usuário está bloqueando pop-ups. Isso ocorre mais comumente quando o navegador é Edge Legacy e o domínio do suplemento está em zona de segurança diferente do domínio que a caixa de diálogo está tentando abrir. Outro cenário que dispara esse erro é que o navegador é o Safari e ele está configurado para bloquear todos os pop-ups. Considere responder a esse erro com um prompt para que o usuário altere a configuração do navegador ou use um navegador diferente.

Quando displayDialogAsync é chamado, ele passa um objeto AsyncResult para sua função de retorno de chamada. Quando a chamada é bem-sucedida, a caixa de diálogo é aberta e a value propriedade do AsyncResult objeto é um objeto Dialog . Para obter um exemplo disso, consulte Enviar informações da caixa de diálogo para a página do host. Quando a chamada a displayDialogAsync falhar, a caixa de diálogo não é criada, a status propriedade do AsyncResult objeto é definida como Office.AsyncResultStatus.Failed, e a error propriedade do objeto é preenchida. Você sempre deve fornecer um retorno de chamada que testa o status e responde quando é um erro. Para obter um exemplo que relata a mensagem de erro independentemente de seu 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 no suplemento, consulte Exemplo de API 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 levantarão um DialogEventReceived evento na página do host. Para obter um lembrete do que é uma página de host, consulte Abrir uma caixa de diálogo de uma página de host.

Número do código	Significado
12002	Uma destas opções: - Não existe uma página na URL transmitida para displayDialogAsync. - A página que foi passada para displayDialogAsync carregada, mas a caixa de diálogo foi redirecionada para uma página que não pode encontrar ou carregar ou foi direcionada para uma URL com sintaxe inválida.
12003	A caixa de diálogo foi direcionada para uma URL com o protocolo HTTP. HTTPS é necessário.
12006	A caixa de diálogo foi fechada, geralmente porque o usuário escolheu o botão FecharX.

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 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;
    }
}

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.