Gérer les erreurs et les événements dans la boîte de dialogue Office
Cet article explique comment intercepter et gérer les erreurs lors de l’ouverture de la boîte de dialogue et les erreurs qui se produisent à l’intérieur de la boîte de dialogue.
Remarque
Cet article suppose que vous connaissez les principes de base de l’utilisation de l’API de boîte de dialogue Office, comme décrit dans Utiliser l’API de boîte de dialogue Office dans vos compléments Office.
Voir aussi Bonnes pratiques et règles pour l’API de boîte de dialogue Office.
Votre code doit gérer deux catégories d’événements.
- les erreurs renvoyées par l’appel de
displayDialogAsynccar la boîte de dialogue ne peut pas être créée ; - Erreurs et autres événements dans la boîte de dialogue.
Erreurs provenant de displayDialogAsync
En plus des erreurs système et de plateforme générales, quatre erreurs sont spécifiques à l’appel displayDialogAsyncde .
| Numéro de code | Signification |
|---|---|
| 12004 | Le domaine de l’URL passée à displayDialogAsync n’est pas approuvé. Le domaine doit être le même domaine que celui de la page hôte (y compris le protocole et le numéro de port). |
| 12005 | L’URL transmise à displayDialogAsync utilise le protocole HTTP. C’est le protocole HTTPS qui est requis. (Dans certaines versions d’Office, le texte du message d’erreur retourné avec 12005 est le même que celui retourné pour 12004.) |
| 12007 | Une boîte de dialogue est déjà ouverte à partir de cette fenêtre hôte. Une fenêtre hôte, par exemple un volet Office, ne peut avoir qu’une seule boîte de dialogue ouverte à la fois. |
| 12009 | L’utilisateur a choisi d’ignorer la boîte de dialogue. Cette erreur peut se produire dans Office sur le Web, où les utilisateurs peuvent choisir de ne pas autoriser un complément à présenter une boîte de dialogue. Pour plus d’informations, consultez Gestion des bloqueurs de fenêtres contextuelles avec Office sur le Web. |
| 12011 | Le complément s’exécute dans Office sur le Web et la configuration du navigateur de l’utilisateur bloque les fenêtres contextuelles. Cela se produit le plus souvent lorsque le navigateur est Edge Hérité et que le domaine du complément se trouve dans une zone de sécurité différente du domaine que la boîte de dialogue tente d’ouvrir. Un autre scénario qui déclenche cette erreur est que le navigateur est Safari et qu’il est configuré pour bloquer toutes les fenêtres contextuelles. Envisagez de répondre à cette erreur en invitant l’utilisateur à modifier la configuration de son navigateur ou à utiliser un autre navigateur. |
Quand displayDialogAsync est appelé, il passe un objet AsyncResult à sa fonction de rappel. Lorsque l’appel réussit, la boîte de dialogue est ouverte et la value propriété de l’objet AsyncResult est un objet Dialog . Pour obtenir un exemple de ceci, consultez Envoyer des informations de la boîte de dialogue à la page hôte. Lorsque l’appel à displayDialogAsync échoue, la boîte de dialogue n’est pas créée, la status propriété de l’objet AsyncResult est définie sur Office.AsyncResultStatus.Failedet la error propriété de l’objet est remplie. Vous devez toujours fournir un rappel qui teste et status répond lorsqu’il s’agit d’une erreur. Pour obtenir un exemple qui signale le message d’erreur quel que soit son numéro de code, consultez le code suivant. (La showNotification fonction, non définie dans cet article, affiche ou journalise l’erreur. Pour obtenir un exemple de la façon dont vous pouvez implémenter cette fonction dans votre complément, consultez Exemple d’API de boîte de dialogue de complément 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);
}
});
Erreurs et événements dans la boîte de dialogue
Trois erreurs et événements dans la boîte de dialogue déclenchent un DialogEventReceived événement dans la page hôte. Pour un rappel de ce qu’est une page hôte, consultez Ouvrir une boîte de dialogue à partir d’une page hôte.
| Numéro de code | Signification |
|---|---|
| 12002 | Un des éléments suivants :
|
| 12003 | La boîte de dialogue a été redirigée vers une URL avec le protocole HTTP. C’est le protocole HTTPS qui est requis. |
| 12006 | Un des éléments suivants :
|
Votre code peut attribuer un gestionnaire pour l’événement DialogEventReceived dans l’appel de displayDialogAsync. Voici un exemple simple.
let dialog;
Office.context.ui.displayDialogAsync('https://myDomain/myDialog.html',
function (result) {
dialog = result.value;
dialog.addEventHandler(Office.EventType.DialogEventReceived, processDialogEvent);
}
);
Pour obtenir un exemple de gestionnaire pour l’événement DialogEventReceived qui crée des messages d’erreur personnalisés pour chaque code d’erreur, consultez l’exemple suivant.
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;
}
}
Voir aussi
Pour voir un exemple de complément qui gère les erreurs de cette façon, consultez la rubrique relative à l’exemple d’API de dialogue de complément Office.