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

Cet article fournit des règles, des limitations et des meilleures pratiques pour l’API de boîte de dialogue Office, notamment des pratiques recommandées pour concevoir l’interface utilisateur d’une boîte de dialogue et utiliser 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 transmettez à la méthode displayDialogAsync doit se trouver exactement 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 d’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 soit un volet Office, soit 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 les API requises.)

• 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 la nouvelle version d’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 Cross-Origin-Opener-Policy : Same-Origin Response, votre complément ne peut pas accéder aux messages de la boîte de dialogue et vos utilisateurs voient l’erreur 12006. Pour éviter cette erreur, définissez l’en-tête sur Cross-Origin-Opener-Policy: unsafe-none ou configurez votre complément et votre boîte de dialogue de sorte qu’ils soient dans le même domaine.

• Dans Outlook sur le web et la nouvelle version d’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 maintenir les window.name fonctionnalités entre les redirections de page.

Meilleures pratiques

Évitez d’abuser 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.

Concevoir une interface utilisateur de boîte de dialogue

Pour consulter les meilleures pratiques en matière de conception de boîtes de dialogue, voir Boîtes de dialogue dans 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 lors de l’utilisation d’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 displayDialogAsync méthode renvoie l’erreur 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 pour l’informer que le complément exige qu’il autorise la boîte de dialogue. Pour plus d’informations sur l’erreur 12009, consultez Erreurs de displayDialogAsync.

Gérer les boîtes de dialogue bloquées (erreur 12009)

Votre complément doit toujours gérer l’erreur 12009 de manière appropriée. Voici quelques approches recommandées :

• Affichez 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.
      }
    }
  );
  

• Proposez 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 être refusé. Effectuez cette requête en utilisant l’objet DialogOptions que vous passez à la displayDialogAsync méthode. Plus précisément, incluez promptBeforeOpen: false dans l’objet. Lorsque vous attribuez la valeur false à cette option, 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 la nouvelle version d’Outlook sur Windows

Si votre complément nécessite l’accès aux fonctionnalités de l’appareil d’un utilisateur, utilisez l’API d’autorisation de l’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 d’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 les paramètres de votre requête personnalisée, le cas échéant. Elle n’ajoute pas ce paramètre aux URL suivantes vers lesquelles 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 en avoir fermé une

Vous ne pouvez pas avoir plusieurs boîtes de dialogue ouvertes à partir d’une page hôte donnée, par conséquent votre code doit 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 , il se peut que la première boîte de closedialogue ne soit pas complètement fermée quand Office tente d’ouvrir la seconde. Dans ce cas, Office renvoie l’erreur 12007 : « L’opération a échoué, car ce complément comporte 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, de sorte qu’elle ne peut 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 une nouvelle boîte de dialogue immédiatement après avoir fermé une boîte de dialogue : encapsulez le code pour ouvrir la nouvelle boîte de dialogue dans une fonction et concevez la fonction pour qu’elle s’appelle récursivement 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.
      }
    }
  );
}

Meilleures pratiques pour l’utilisation de l’API de boîte de dialogue Office dans un SPA

Si votre complément utilise le routage côté client, comme le font généralement les applications monopage (SPA), vous pouvez transmettre l’URL d’une route à la méthode displayDialogAsync plutôt que 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 sites web d’application monopage (SPA) 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 transmettez une route, votre page de base et tout son code d’initialisation et d’amorçage 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 fenêtre de dialogue de la boîte, ce qui va partiellement à l’encontre de l’objectif d’un SPA. En outre, le code qui modifie des 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 possède 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ée ressemblent à deux clients différents pour votre serveur. (Pour un rappel de ce qu’est une page d’hôte, voir Ouvrir une boîte de dialogue à partir d’une page d’hôte.)

Par conséquent, si vous passez une route vers la displayDialogAsync méthode, vous n’avez pas vraiment de SPA ; vous avez deux instances de la même SPA. En outre, une grande partie du code figurant dans le volet Office instance n’est jamais utilisée dans ce instance et une grande partie du code dans la boîte de dialogue instance n’est jamais utilisée dans ce instance. C’est comme avoir deux SPA dans le même bundle.

Recommandations Microsoft

Au lieu de passer une voie 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 SPA différentes ; autrement dit, avoir deux SPA dans différents dossiers 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 de tels cas, votre projet est grandement simplifié en hébergeant une seule page HTML, avec JavaScript intégré ou référencé, dans le domaine de votre SPA. Passez l’URL de la page à la méthodedisplayDialogAsync. Bien que cette approche implique que vous vous écartez de l’idée littérale d’une application monopage, vous n’avez pas vraiment une seule instance d’un 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