Bonnes pratiques et règles pour l’API boîte de dialogue Office

Cet article fournit des règles, des limitations et des meilleures pratiques pour l’API boîte de dialogue Office, notamment les meilleures pratiques pour la conception de l’interface utilisateur d’un dialogue et l’utilisation de l’API dans une application monopage (SPA).

Règles et limitations

• Une boîte de dialogue peut uniquement accéder aux URL HTTPS, et non à HTTP.

• L’URL que vous passez à la méthode displayDialogAsync doit se trouver dans le même domaine que le complément lui-même. Il ne peut pas s’agir d’un sous-domaine. Toutefois, la page que vous lui transmettez peut rediriger vers une page dans un autre domaine.

• Une page hôte ne peut avoir qu’une seule boîte de dialogue ouverte à la fois. La page hôte peut être un volet Office ou le fichier de fonction d’une commande de fonction. Vous pouvez ouvrir plusieurs boîtes de dialogue en même temps à partir de boutons de ruban personnalisés ou d’éléments de menu.

• La boîte de dialogue ne peut appeler que deux API Office :

  • Office.context.ui.messageParent
  • Office.context.requirements.isSetSupported (Pour plus d’informations, voir Spécifier les applications Office et la configuration requise de l’API.)

• Vous appelez généralement la fonction messageParent à partir d’une page dans le même domaine que le complément lui-même, mais ce n’est pas obligatoire. Pour plus d’informations, consultez Messagerie inter-domaines au runtime hôte.

• Lorsqu’une boîte de dialogue s’ouvre, elle est centrée sur l’écran au-dessus de l’application Office.

• L’utilisateur peut déplacer et redimensionner une boîte de dialogue.

• Une boîte de dialogue s’affiche dans l’ordre dans lequel elle est créée.

  Conseil

  Dans Office sur le Web et outlook sur Windows, si le domaine de votre boîte de dialogue est différent de celui de votre complément et qu’il applique l’en-tête de réponse Cross-Origin-Opener-Policy : same-origin, votre complément est bloqué pour accéder aux messages à partir de la boîte de dialogue et vos utilisateurs voient l’erreur 12006. Pour éviter cette erreur, définissez l’en-tête Cross-Origin-Opener-Policy: unsafe-none sur ou configurez votre complément et boîte de dialogue pour qu’il se trouve dans le même domaine.

• Dans Outlook sur le web et outlook sur Windows, ne définissez pas la propriété window.name lors de la configuration d’une boîte de dialogue dans votre complément. Ces clients Outlook utilisent la propriété pour gérer les window.name fonctionnalités des redirections de page.

Meilleures pratiques

Éviter la surutilisation des boîtes de dialogue

Comme des éléments d’interface utilisateur qui se chevauchent peuvent gêner des utilisateurs, évitez d’ouvrir une boîte de dialogue à partir d’un volet Office à moins que votre scénario l’exige. Lorsque vous envisagez d’utiliser la surface d’exposition d’un volet Office, tenez compte du fait que les volets Office peuvent être affichés sous forme d’onglets. Pour obtenir un exemple de volet Office à onglets, consultez l’exemple De complément Excel JavaScript SalesTracker .

Concevoir une interface utilisateur de boîte de dialogue

Pour connaître les meilleures pratiques en matière de conception de boîte de dialogue, voir Boîtes de dialogue dans les compléments Office.

Gérer les bloqueurs de fenêtres contextuelles avec Office sur le Web

Si vous essayez d’afficher une boîte de dialogue tout en utilisant Office sur le Web, le bloqueur de fenêtres contextuelles du navigateur peut bloquer la boîte de dialogue. Pour éviter ce problème, Office sur le Web invite l’utilisateur à Autoriser ou Ignorer l’ouverture de la boîte de dialogue.

Si l’utilisateur choisit Autoriser, la boîte de dialogue Office s’ouvre. Si l’utilisateur choisit Ignorer, l’invite se ferme et la boîte de dialogue Office ne s’ouvre pas. Au lieu de cela, la méthode retourne l’erreur displayDialogAsync 12009. Votre code doit intercepter cette erreur et fournir une autre expérience qui ne nécessite pas de boîte de dialogue, ou afficher un message à l’utilisateur indiquant que le complément l’exige pour autoriser la boîte de dialogue. Pour plus d’informations sur l’erreur 12009, consultez Erreurs de displayDialogAsync.

Gérer les dialogues bloqués (erreur 12009)

Votre complément doit toujours gérer l’erreur 12009 correctement. Voici quelques approches recommandées :

• Afficher un message convivial qui explique pourquoi la boîte de dialogue est nécessaire.

  Office.context.ui.displayDialogAsync(
    "https://www.contoso.com/auth.html",
    { height: 60, width: 30 },
    (asyncResult) => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        if (asyncResult.error.code === 12009) {
          // User blocked the dialog.
          showNotification(
            "Dialog Required",
            "This add-in needs to open a dialog to sign you in. " +
            "Please click the add-in button again and choose 'Allow' when prompted."
          );
        } else {
          // Handle other errors.
          showNotification("Error", `Unable to open dialog: ${asyncResult.error.message}`);
        }
      } else {
        // Dialog opened successfully.
        const dialog = asyncResult.value;
        // ... Handle dialog events here.
      }
    }
  );
  

• Fournissez un autre flux de travail lorsque cela est possible. Si votre complément peut fonctionner avec des fonctionnalités réduites lorsque la boîte de dialogue est bloquée, proposez cette alternative à l’utilisateur.

Désactivation de l’invite

Si vous souhaitez désactiver l’invite autoriser/ignorer, votre code doit désactiver. Effectuez cette requête à l’aide de l’objet DialogOptions que vous passez à la displayDialogAsync méthode . Plus précisément, incluez promptBeforeOpen: false dans l’objet . Lorsque vous définissez cette option sur false, Office sur le Web n’invite pas l’utilisateur à autoriser le complément à ouvrir une boîte de dialogue, et la boîte de dialogue Office ne s’ouvre pas si le bloqueur de fenêtres contextuelles du navigateur le bloque.

Demander l’accès aux fonctionnalités de l’appareil dans Office sur le Web et outlook sur Windows

Si votre complément nécessite l’accès aux fonctionnalités d’appareil d’un utilisateur, utilisez l’API d’autorisation d’appareil pour demander des autorisations via une boîte de dialogue. Les fonctionnalités de l’appareil incluent la caméra, la géolocalisation et le microphone d’un utilisateur. Cette exigence s’applique aux applications Office suivantes.

• Office sur le Web (Excel, Outlook, PowerPoint et Word) s’exécutant dans des navigateurs basés sur Chromium, tels que Microsoft Edge ou Google Chrome
• nouvel Outlook sur Windows

Lorsque votre complément appelle Office.context.devicePermission.requestPermissions ou Office.context.devicePermission.requestPermissionsAsync, une boîte de dialogue s’affiche avec les fonctionnalités de l’appareil demandées et les options Autoriser, Autoriser une fois ou Refuser l’accès. Pour plus d’informations, voir Afficher, gérer et installer des compléments pour Excel, PowerPoint et Word.

N’utilisez pas la valeur _host_info

Office ajoute automatiquement un paramètre de requête nommé _host_info à l’URL qui est passée à displayDialogAsync. Il ajoute ce paramètre après vos paramètres de requête personnalisés, le cas échéant. Il n’ajoute pas ce paramètre aux URL suivantes auxquelles la boîte de dialogue accède. Microsoft peut modifier le contenu de cette valeur ou la supprimer entièrement, de sorte que votre code ne doit pas la lire. La même valeur est ajoutée au stockage de session de la boîte de dialogue (autrement dit, la propriété Window.sessionStorage ). Là encore, votre code ne doit ni lire, ni écrire cette valeur.

Ouvrir une autre boîte de dialogue immédiatement après la fermeture d’une boîte de dialogue

Vous ne pouvez pas avoir plusieurs boîtes de dialogue ouvertes à partir d’une page hôte donnée. Votre code doit donc appeler Dialog.close sur une boîte de dialogue ouverte avant d’appeler displayDialogAsync pour ouvrir une autre boîte de dialogue. La close méthode est asynchrone. Pour cette raison, si vous appelez displayDialogAsync immédiatement après un appel de , la première boîte de closedialogue peut ne pas être complètement fermée quand Office tente d’ouvrir la seconde. Si cela se produit, Office renvoie une erreur 12007 : « L’opération a échoué, car ce complément a déjà une boîte de dialogue active . »

La close méthode n’accepte pas de paramètre de rappel et ne retourne pas d’objet Promise. Elle ne peut donc pas être attendue avec le await mot clé ou avec une then méthode. Pour cette raison, utilisez la technique suivante lorsque vous devez ouvrir un nouveau dialogue immédiatement après la fermeture d’un dialogue : encapsuler le code pour ouvrir le nouveau dialogue dans une fonction et concevoir la fonction pour qu’elle s’appelle de manière récursive si l’appel de displayDialogAsync retourne 12007. L’exemple suivant montre comment implémenter cette technique.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/firstDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        openSecondDialog();
      }
      else {
         // Handle errors.
      }
    }
  );
}
 
function openSecondDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/secondDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        if (result.error.code === 12007) {
          openSecondDialog(); // Recursive call.
        }
        else {
         // Handle other errors.
        }
      }
    }
  );
}

Vous pouvez également forcer le code à s’interrompre avant d’essayer d’ouvrir la deuxième boîte de dialogue à l’aide de la méthode setTimeout . L’exemple suivant montre comment implémenter cette approche.

function openFirstDialog() {
  Office.context.ui.displayDialogAsync(
    "https://MyDomain/firstDialog.html",
    { width: 50, height: 50 },
    (result) => {
      if (result.status === Office.AsyncResultStatus.Succeeded) {
        const dialog = result.value;
        dialog.close();
        setTimeout(() => { 
          Office.context.ui.displayDialogAsync(
            "https://MyDomain/secondDialog.html",
            { width: 50, height: 50 },
            (result) => {
              // Callback body.
            }
          );
        }, 1000);
      }
      else {
         // Handle errors.
      }
    }
  );
}

Bonnes pratiques pour l’utilisation de l’API de boîte de dialogue Office dans une application spa

Si votre complément utilise le routage côté client, comme le font généralement les applications monopages,vous pouvez passer l’URL d’un itinéraire à la méthode displayDialogAsync au lieu de l’URL d’une page HTML distincte. N’utilisez pas cette approche pour les raisons indiquées dans la section suivante.

Problèmes liés aux spAs et à l’API de boîte de dialogue Office

La boîte de dialogue Office se trouve dans une nouvelle fenêtre avec sa propre instance du moteur JavaScript, et donc son propre contexte d’exécution complet. Si vous passez un itinéraire, votre page de base et tout son code d’initialisation et de démarrage s’exécutent à nouveau dans ce nouveau contexte, et toutes les variables sont définies sur leurs valeurs initiales dans la boîte de dialogue. Cette technique télécharge et lance donc une deuxième instance de votre application dans la boîte de dialogue de la fenêtre de boîte de dialogue, ce qui va à l’échec de l’objectif d’une spa. En outre, le code qui modifie les variables dans la fenêtre de boîte de dialogue ne modifie pas la version du volet Office des mêmes variables. De même, la fenêtre de boîte de dialogue a son propre stockage de session (propriété Window.sessionStorage ), qui n’est pas accessible à partir du code dans le volet Office. La boîte de dialogue et la page hôte sur laquelle displayDialogAsync a été appelé ressemblent à deux clients différents pour votre serveur. (Pour un rappel de ce qu’est une page hôte, consultez Ouvrir une boîte de dialogue à partir d’une page hôte.)

Ainsi, si vous passez un itinéraire à la displayDialogAsync méthode, vous n’avez pas vraiment d’spa ; vous avez deux instances de la même spa. En outre, une grande partie du code du volet Office instance n’est jamais utilisé dans cette instance et une grande partie du code de la boîte de dialogue instance n’est jamais utilisé dans cette instance. C’est comme avoir deux spas dans la même offre groupée.

Recommandations Microsoft

Au lieu de passer un itinéraire côté client à la displayDialogAsync méthode, utilisez l’une des approches suivantes.

• Si le code que vous souhaitez exécuter dans la boîte de dialogue est suffisamment complexe, créez explicitement deux spas différents . autrement dit, avoir deux spas dans des dossiers différents du même domaine. Un spa s’exécute dans la boîte de dialogue et l’autre dans la page hôte de la boîte de dialogue où displayDialogAsync a été appelé.
• Dans la plupart des scénarios, seule une logique simple est nécessaire dans la boîte de dialogue. Dans ce cas, votre projet est considérablement simplifié en hébergeant une seule page HTML, avec JavaScript incorporé ou référencé, dans le domaine de votre SPA. Passez l’URL de la page à la méthodedisplayDialogAsync. Bien que cette approche signifie que vous vous écartez de l’idée littérale d’une application monopage, vous n’avez pas vraiment une seule instance d’une spa lorsque vous utilisez l’API de boîte de dialogue Office.

Voir aussi

• Utiliser l’API boîte de dialogue Office dans les compléments Office
• Gérer les erreurs et les événements dans la boîte de dialogue Office