Pratiques recommandées et règles pour l’API de dialogue Office

Cet article fournit des règles, des règles et des bonnes pratiques pour l’API de 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 pièges

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

• L’URL transmise à 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 qui lui est transmise peut être redirigée 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.

• Seules deux API Office peuvent être appelées dans la boîte de dialogue ,

  • 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.)

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

  Conseil

  Dans Office sur le web et le nouvel 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 sera bloqué pour accéder aux messages de la boîte de dialogue et vos utilisateurs verront l’erreur 12006. Pour éviter cela, vous devez définir l’en-tête Cross-Origin-Opener-Policy: unsafe-none sur ou configurer votre complément et votre boîte de dialogue pour qu’il se trouve dans le même domaine.

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 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 cela, 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 12009, consultez Erreurs de displayDialogAsync.)

Si, pour une raison quelconque, vous souhaitez désactiver cette fonctionnalité, votre code doit refuser. Il effectue cette requête avec l’objet DialogOptions qui est passé à la displayDialogAsync méthode . Plus précisément, l’objet doit inclure promptBeforeOpen: false. Lorsque cette option est définie 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.

Demander l’accès aux fonctionnalités des appareils 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, une boîte de dialogue pour demander des autorisations est disponible via l’API d’autorisation de l’appareil. Les fonctionnalités de l’appareil incluent la caméra, la géolocalisation et le microphone d’un utilisateur. Cela 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 appelé _host_info à l’URL qui est transmise à displayDialogAsync. Il est ajouté après vos paramètres de requête personnalisés, le cas échéant. Il n’est pas ajouté aux URL suivantes auxquelles la boîte de dialogue accède. Microsoft peut modifier le contenu de cette valeur ou le 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 le deuxième. 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, de sorte qu’elle ne peut pas être attendue avec le await mot clé ou avec une then méthode. Pour cette raison, nous vous suggérons 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. Voici un exemple.

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 . Voici un exemple.

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 monopage (SPAs), vous avez la possibilité de passer l’URL d’un itinéraire à la méthode displayDialogAsync au lieu de l’URL d’une page HTML distincte. Nous vous déconseillons de le faire pour les raisons indiquées ci-dessous.

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. Par conséquent, cette technique télécharge et lance une deuxième instance de votre application dans la fenêtre box, ce qui contredise partiellement 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.)

Par conséquent, si vous avez passé un itinéraire à la displayDialogAsync méthode, vous n’auriez pas vraiment d’spa ; vous auriez deux instances de la même spa. En outre, une grande partie du code dans l’instance du volet Office ne serait jamais utilisée dans cette instance et une grande partie du code dans l’instance de boîte de dialogue ne serait jamais utilisée dans cette instance. Ce serait comme avoir deux SPAs dans le même lot.

Recommandations Microsoft

Au lieu de passer un itinéraire côté client à la displayDialogAsync méthode, nous vous recommandons d’effectuer l’une des opérations 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 sera 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 cela signifie 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.