Processar erros e eventos na caixa de diálogo do Office
Este artigo descreve como intercetar e processar erros ao abrir a caixa de diálogo e erros que ocorrem dentro da caixa de diálogo.
Observação
Este artigo pré-configura que está familiarizado com as noções básicas da utilização da API de caixa de diálogo do Office, conforme descrito em Utilizar a API de caixa de diálogo do Office nos seus Suplementos do Office.
Consulte também Melhores práticas e regras para a API de caixa de diálogo do Office.
O código deve processar duas categorias de eventos.
- Erros devolvidos pela chamada de
displayDialogAsyncporque não é 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 da chamada displayDialogAsync.
| Número do código | Significado |
|---|---|
| 12004 | O domínio do URL transmitido para displayDialogAsync não é fidedigno. 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).No Outlook na Web e no novo Outlook no Windows, este erro ocorre quando um suplemento está alojado num servidor localhost e o respetivo manifesto não especifica um elemento AppDomain para localhost. |
| 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 devolvido com 12005 é o mesmo devolvido 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. Este erro pode ocorrer no Office na Web, em que os utilizadores podem optar por não permitir que um suplemento apresente uma caixa de diálogo. Para obter mais informações, veja Handling pop-up blockers with Office na Web (Processar bloqueadores de pop-up com Office na Web). |
| 12011 | O suplemento está em execução no Office na Web e a configuração do browser do utilizador está a bloquear pop-ups. Isto acontece normalmente quando o browser é Legado do Edge e o domínio do suplemento está numa zona de segurança diferente do domínio que a caixa de diálogo está a tentar abrir. Outro cenário que aciona este erro é que o browser é o Safari e está configurado para bloquear todos os pop-ups. Considere responder a este erro com um pedido ao utilizador para alterar a configuração do browser ou utilizar um browser diferente. |
Quando displayDialogAsync é chamado, transmite um objeto AsyncResult para a função de chamada de retorno. Quando a chamada é efetuada com êxito, a caixa de diálogo é aberta e a value propriedade do AsyncResult objeto é um objeto caixa de diálogo . Para obter um exemplo disto, consulte Enviar informações da caixa de diálogo para a página do anfitrião. Quando a chamada para displayDialogAsync falha, a caixa de diálogo não é criada, a status propriedade do AsyncResult objeto é definida como Office.AsyncResultStatus.Failede a error propriedade do objeto é preenchida. Deve sempre fornecer uma chamada de retorno que teste o status e responda quando se trata de um erro. Para obter um exemplo que reporta a mensagem de erro independentemente do respetivo número de código, veja o seguinte código. (A showNotification função, não definida neste artigo, apresenta ou regista o erro. Para obter um exemplo de como pode implementar esta função no 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 anfitrião. Para um lembrete do que é uma página de anfitrião, consulte Abrir uma caixa de diálogo a partir de uma página de anfitrião.
| Número do código | Significado |
|---|---|
| 12002 | Uma destas opções:
|
| 12003 | A caixa de diálogo foi direcionada para uma URL com o protocolo HTTP. HTTPS é necessário. |
| 12006 | Uma das seguintes opções:
|
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 processador para o DialogEventReceived evento que cria mensagens de erro personalizadas para cada código de erro, veja o exemplo seguinte.
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.