Travailler avec les boîtes de dialogue

Effectué

Dans cette section, vous découvrirez comment incorporer des boîtes de dialogue dans les classeurs Excel. Vous allez découvrir comment ouvrir les boîtes de dialogue et comment soumettre et extraire des entrées et des sorties pour la boîte de dialogue.

Boîtes de dialogue

L’API de dialogue est une extension de l’expérience utilisateur que les développeurs peuvent personnaliser dans Office. Les développeurs peuvent l’utiliser pour ouvrir des boîtes de dialogue à partir de compléments personnalisés qui interagissent avec l’utilisateur et l’expérience utilisateur de complément personnalisé.

Le scénario principal pour l'API de dialogue est l'authentification auprès de fournisseurs tiers. La plupart des fournisseurs d’identité empêchent leurs expériences de connexion d’être affichées dans un <iframe> en raison de problèmes de clic. Cela pose problème avec un complément, car ils sont affichés dans <iframe>dans certains clients tels que les versions web des applications clientes Office.

Une autre difficulté avec les scénarios d’authentification est de prédire les domaines qui doivent être chargés. Dans les scénarios de connexion fédérée, la liste potentielle des domaines peut être infinie, ce qui est à nouveau problématique dans un complément dans lequel tous les domaines doivent être enregistrés dans le manifeste.

Il est important de noter qu'Office offre une expérience d’authentification unique propre aux identités Microsoft. Si votre complément nécessite des données sur l'utilisateur d'Office ou ses ressources accessibles via Microsoft Graph, comme Microsoft 365 ou OneDrive, Microsoft vous recommande d'utiliser l' API d'authentification unique chaque fois que vous le pouvez. Si vous utilisez les API pour l’authentification unique, vous n’avez pas besoin de l’API de dialogue.

Au-delà de l’authentification, l’API Boîte de dialogue peut fournir davantage de surface d’écran pour les éléments difficiles à afficher dans un volet des tâches classique du complément de contenu. Un bon exemple serait d’héberger une vidéo qui serait trop petite si elle était limitée à un volet des tâches.

L’API de dialogue peut afficher n’importe quelle page Web HTTPS, mais celle-ci doit d’abord être lancée vers un domaine d’application avant d’être redirigée.

Boîtes de dialogue ouvertes

Ouvrir une boîte de dialogue à l’aide de la méthode displayDialogAsync() à partir d’un complément Office :

Office.context.ui.displayDialogAsync("<URL />", options, optionalCallback);

La méthode displayDialogAsync() accepte trois paramètres :

• La <URL /> est la page à afficher dans la boîte de dialogue. Il s'agit tout d'abord d'une page hébergée à partir d'un domaine d'application tel que défini dans le manifeste. Toutefois, la page peut être immédiatement redirigée vers une autre page.

• Le paramètre options permet au développeur de modifier la taille de la boîte de dialogue. Par défaut, la boîte de dialogue s'affiche à 80 % de la hauteur et de la largeur de l'écran de l'appareil. Les valeurs de hauteur et de largeur sont exprimées en pourcentage de l’écran de l’appareil.

  Les développeurs peuvent éventuellement définir la propriété displayInIframe dans les options. Si vous définissez cette propriété sur true, la boîte de dialogue s’affiche comme une IFrame flottante plutôt qu’une fenêtre indépendante (dans les clients qui la prennent en charge), ce qui permet de l’ouvrir plus rapidement.

• La optionalCallback permet à la page hôte de complément de répondre aux messages et événements à partir de la boîte de dialogue.

Entrée et sortie de boîte de dialogue

Le moyen principal de transmettre des informations à une boîte de dialogue est de passer par le stockage local du navigateur (window.localStorage) ou par les paramètres d’URL dans l’URL de la boîte de dialogue. Dans cet exemple, la page hôte transmet un ID de « 123 » à la boîte de dialogue via un paramètre d’URL.

/******* START Host page script *******/

// Open the dialog passing the parameter id=123
let dialog = null;
Office.context.ui.displayDialogAsync(
  'https://domain/popup.html?id=123',
  {
    height: 45,
    width: 55
  },
  function(result) {
    dialog = result.value;
    // Listen for messages coming from the dialog
    dialog.addEventHandler(
      Microsoft.Office.WebExtension.EventType.DialogMessageReceived,
      processMessage
    );
  }
);
function processMessage(arg) {
  // Log the message send from the dialog and close the dialog
  console.log(arg.message);
  dialog.close();
}
/******* End Host page script *******/

/******* Start Dialog page script *******/
// dialog must call Office.initialize
Office.initialize = function() {
  // send the parent/host a message
  Office.context.ui.messageParent('Hello from the dialog!!!');
}

Une boîte de dialogue peut renvoyer des messages à l'hôte en appelant Office.context.ui.messageParent pour envoyer une valeur booléenne ou un message de type chaîne à la page hôte. En bas de l’exemple, vous pouvez voir le script de boîte de dialogue où il transmet le message « Hello from the dialog !! » au parent.

La méthode messageParent() peut uniquement être appelée sur une page ayant le même domaine (y compris les mêmes protocole et port) que la page hôte.

La page hôte doit écouter les messages en s’inscrivant au gestionnaire DialogMessageReceived. Dans l’exemple, la page hôte enregistre ce gestionnaire à l’aide de la fonction processMessage(), où il journalise le message sur la console.

Résumé

Dans cette unité, vous avez découvert comment incorporer des boîtes de dialogue dans les classeurs Excel. Vous avez également découvert comment ouvrir les boîtes de dialogue et comment soumettre et extraire des entrées et des sorties pour la boîte de dialogue.

Continuer