Exercice : utiliser des boîtes de dialogue dans Excel

  • 11 minutes

Les boîtes de dialogue du complément Office sont non modales. Cela signifie qu’un utilisateur peut continuer à interagir, à la fois avec le document dans l’application hôte Office, et avec la page hôte dans le volet Office.

Dans cet exercice, vous allez ouvrir une boîte de dialogue dans votre complément, transmettre un message du processus de boîte de dialogue au processus de volet des tâches et fermer la boîte de dialogue.

Création de la page de boîte de dialogue

  1. Dans le dossier ./src situé à la racine du projet, créez un dossier nommé boîtes de dialogue.

  2. Dans le dossier ./src/dialogs, créez un fichier nommé popup.html.

  3. Ajoutez le balisage suivant au fichier popup.html. Remarque :

    • La page comporte un champ <input>, dans lequel l’utilisateur entrera son nom, et un bouton qui permet d’envoyer le nom à la page dans le volet Office où il sera affiché.
    • Le balisage charge un script nommé popup.js que vous allez créer dans une étape ultérieure.
    • Il charge également la bibliothèque Office.js, car elle sera utilisée dans popup.js.
    <!DOCTYPE html>
<html>
  <head lang="en">
    <title>Dialog for My Office Add-in</title>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">

    <!-- For more information on Office UI Fabric, visit https://developer.microsoft.com/fabric. -->
    <link rel="stylesheet" href="https://static2.sharepointonline.com/files/fabric/office-ui-fabric-core/9.6.1/css/fabric.min.css"/>

    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js"></script>
    <script type="text/javascript" src="popup.js"></script>
  </head>
  <body style="display:flex;flex-direction:column;align-items:center;justify-content:center">
    <p class="ms-font-xl">ENTER YOUR NAME</p>
    <input id="name-box" type="text"/><br/><br/>
    <button id="ok-button" class="ms-Button">OK</button>
  </body>
</html>

  4. Dans le dossier ./src/dialogs, créez un fichier nommé popup.js.

  5. Ajoutez le code suivant au fichier popup.js :

    (async () => {
  await Office.onReady();

  // TODO1: Assign handler to the OK button.

  // TODO2: Create the OK button handler
})();

    Remarque

    • Toutes les pages appellent les API dans la bibliothèque Office.js doivent tout d’abord vérifier que la bibliothèque est entièrement initialisée. La meilleure façon de procéder consiste à appeler la méthode Office.onReady(). Si votre complément dispose de ses propres tâches d’initialisation, le code doit passer dans une méthode then() chaînée à l’appel de Office.onReady(). Le code qui appelle Office.onReady() doit être exécuté avant d’appeler Office.js ; l’attribution se trouve donc dans un fichier de script chargé par la page, comme c’est le cas ici.

  6. Remplacez TODO1 par le code suivant. Vous allez créer la fonction sendStringToParentPage() à l’étape suivante.

    document.getElementById("ok-button").onclick = sendStringToParentPage;

  7. Remplacez TODO2 par le code suivant. La méthode messageParent() transmet son paramètre à la page parent, qui est, dans ce cas, la page dans le volet Office. Le paramètre peut être une valeur booléenne ou une chaîne qui inclut tous les éléments qui peuvent être sérialisés en tant que chaîne, au format XML ou JSON.

    function sendStringToParentPage() {
  const userName = document.getElementById("name-box").value;
  Office.context.ui.messageParent(userName);
}

Remarque

Le fichier popup.html et le fichier popup.js qu’il charge s’exécutent dans un processus Microsoft Edge ou Internet Explorer 11 entièrement séparé à partir du volet Office du complément. Si le popup.js était transpilé dans le même fichier bundle.js en tant que fichier app.js, le complément devrait charger deux copies du fichier bundle.js, ce qui irait à l’encontre de l’objectif de groupement. Par conséquent, ce complément ne transpile pas le fichier popup.js du tout.

Mettre à jour les paramètres de configuration webapck

Ouvrez le fichier webpack.config.js situé dans le répertoire racine du projet et procédez comme suit.

  1. Recherchez l’objet entry dans l’objet config et ajoutez une nouvelle entrée pour popup.

    popup: "./src/dialogs/popup.js"

    Lorsque c’est chose faite, le nouvel objet entry se présente comme suit :

    entry: {
  polyfill: "@babel/polyfill",
  taskpane: "./src/taskpane/taskpane.js",
  commands: "./src/commands/commands.js",
  popup: "./src/dialogs/popup.js"
},

  2. Recherchez la matrice plugins dans l’objet config et ajoutez l’objet suivant à la fin de cette matrice.

    new HtmlWebpackPlugin({
  filename: "popup.html",
  template: "./src/dialogs/popup.html",
  chunks: ["polyfill", "popup"]
})

    Lorsque c’est chose faite, la nouvelle matrice plugins se présente comme suit :

    plugins: [
  new HtmlWebpackPlugin({
    filename: "taskpane.html",
    template: "./src/taskpane/taskpane.html",
    chunks: ["polyfill", "taskpane"],
  }),
  new CopyWebpackPlugin({
    patterns: [
      {
        from: "assets/*",
        to: "assets/[name][ext][query]",
      },
      {
        from: "manifest*.xml",
        to: "[name]." + buildType + "[ext]",
        transform(content) {
          if (dev) {
            return content;
          } else {
            return content.toString().replace(new RegExp(urlDev, "g"), urlProd);
          }
        },
      },
    ],
  }),
  new HtmlWebpackPlugin({
    filename: "commands.html",
    template: "./src/commands/commands.html",
    chunks: ["polyfill", "commands"],
  }),
  new HtmlWebpackPlugin({
    filename: "popup.html",
    template: "./src/dialogs/popup.html",
    chunks: ["polyfill", "popup"]
  })
],

  3. Si le serveur web local est en cours d’exécution, arrêtez-le en entrant la commande suivante dans l’invite de commandes.

    npm stop

  4. Exécutez la commande suivante pour regénérer le projet.

    npm run build

Ouverture de la boîte de dialogue à partir du volet Office

  1. Ouvrez le fichier ./src/taskpane/taskpane.html.

  2. Recherchez l’élément <button> du bouton freeze-header, puis ajoutez la balise suivante après cette ligne :

    <button class="ms-Button" id="open-dialog">Open Dialog</button><br/><br/>

  3. La boîte de dialogue invitera l’utilisateur à saisir son nom et transmettra ce nom au volet Office. Le volet Office s’affichera dans une étiquette. Immédiatement après le button que vous venez d’ajouter, ajoutez le balisage suivant :

    <label id="user-name"></label><br/><br/>

  4. Ouvrez le fichier ./src/taskpane/taskpane.js.

  5. Dans l’appel de la méthode Office.onReady(), recherchez la ligne suivante :

    document.getElementById("freeze-header").onclick = freezeHeader;

    Ajoutez le code suivant juste après :

    document.getElementById("open-dialog").onclick = openDialog;

  6. Ajoutez la déclaration suivante à la fin du fichier. Cette variable est utilisée pour conserver un objet dans le contexte d’exécution de la page parent qui agit en tant qu’intermédiaire pour le contexte d’exécution de la page de boîte de dialogue.

    let dialog = null;

  7. Ajoutez la fonction suivante à la fin du fichier (après la déclaration de dialog). Ce qui est le plus important à propos de ce code, c’est ce qui ne s’y trouve pas : il n’y a aucun appel de Excel.run(). Cela est dû au fait que l’API qui ouvre une boîte de dialogue est partagée par tous les hôtes Office, et fait donc partie de l’API commune JavaScript Office, et non de l’API spécifique d’Excel.

    function openDialog() {
  // TODO1: Call the Office Common API that opens a dialog
}

  8. Remplacez TODO1 par le code suivant :

    Office.context.ui.displayDialogAsync(
  'https://localhost:3000/popup.html',
  {height: 45, width: 55},

  // TODO2: Add callback parameter.
);

    Remarque

    • La méthode displayDialogAsync() ouvre une boîte de dialogue au centre de l’écran.
    • Le premier paramètre est l’URL de la page à ouvrir.
    • Le deuxième paramètre transmet les options. height et width sont des pourcentages de la taille de la fenêtre de l’application Office.

Traitement du message à partir de la boîte de dialogue et fermeture de la boîte de dialogue

  1. Dans la fonction openDialog() dans le fichier ./src/taskpane/taskpane.js, remplacez TODO2 par le code suivant :

    function (result) {
  dialog = result.value;
  dialog.addEventHandler(Microsoft.Office.WebExtension.EventType.DialogMessageReceived, processMessage);
}

    Remarque

    • Le rappel est exécuté immédiatement après que la boîte de dialogue s’est ouverte correctement et avant que l’utilisateur a pris une quelconque action dans la boîte de dialogue.
    • result.value représente l’objet qui agit comme un intermédiaire entre les contextes d’exécution des pages parent et de boîte de dialogue.
    • La fonction processMessage() sera créée à une étape ultérieure. Ce gestionnaire traitera toutes les valeurs envoyées par la page de boîte de dialogue avec les appels de la fonction messageParent().

  2. Ajoutez la fonction suivante après la fonction openDialog().

    function processMessage(arg) {
  document.getElementById("user-name").innerHTML = arg.message;
  dialog.close();
}

  3. Vérifiez que vous avez enregistré toutes les modifications que vous avez apportées au projet.

Test du complément

  1. Si le serveur web local est déjà en cours d’exécution et que votre complément est déjà chargé dans Excel, passez à l’étape 2. Sinon, démarrez le serveur web local et chargez la version test de votre complément :

    • Pour tester votre complément dans Excel, exécutez la commande suivante dans le répertoire racine de votre projet. Cela a pour effet de démarrer le serveur web local (s’il n’est pas déjà en cours d’exécution) et d’ouvrir Excel avec votre complément chargé.

      npm start

    • Pour tester votre complément dans Excel sur le web, exécutez la commande suivante dans le répertoire racine de votre projet. Lorsque vous exécutez cette commande, le serveur web local démarre (s’il n’est pas déjà en cours d’exécution).

      npm run start:web

      Pour utiliser votre complément, ouvrez un nouveau document dans Excel sur le web, puis chargez la version test de votre complément en suivant les instructions de l’article relatif au chargement de version test des compléments Office dans Office sur le web.

  2. Pour ouvrir le volet Office du complément, sous l’ongletAccueil, sélectionnez Afficher le volet Office.

  3. Sélectionnez Ouvrir la boîte de dialogue.

  4. Lorsque la boîte de dialogue est ouverte, faites-la glisser et redimensionnez-la. Vous pouvez interagir avec la feuille de calcul et appuyez sur les autres boutons du volet Office, mais vous ne pouvez pas lancer une deuxième boîte de dialogue à partir de la même page du volet Office.

  5. Dans la boîte de dialogue, entrez un nom, puis sélectionnez OK. Ce nom apparaît sur le volet Office et la boîte de dialogue se ferme.

  6. Si vous le souhaitez, dans la fonction processMessage, ajoutez // devant le trait dialog.close();. Ensuite, répétez les étapes de cette section. La boîte de dialogue reste ouverte et vous pouvez modifier le nom. Vous pouvez la fermer manuellement en appuyant sur la croix (X) en haut à droite.

Capture d’écran de la boîte de dialogue ajoutée par le didacticiel dans Excel.

Résumé

Dans cet exercice, vous avez ouvert une boîte de dialogue dans votre complément, vous avez transmis un message du processus de boîte de dialogue au processus de volet des tâches et vous avez fermé la boîte de dialogue.

Testez vos connaissances

1.

Comment un complément Office peut-il ouvrir une boîte de dialogue à partir de Microsoft Excel ?

2.

De quelles façons les compléments Office peuvent-ils accéder aux valeurs à partir de la boîte de dialogue ?