Création de votre premier complément Outlook

Dans cet article, vous découvrirez comment créer un complément du volet Office Outlook qui affiche au moins une propriété d’un message sélectionné.

Créer le complément

Vous pouvez créer un complément Office à l’aide du générateur Yeoman pour les compléments Office ou de Visual Studio. Le générateur Yeoman crée un projet Node.js qui peut être géré avec du Visual Studio Code ou n’importe quel autre éditeur, alors que Visual Studio crée une solution Visual Studio. Sélectionnez l’onglet correspondant à votre choix, puis suivez les instructions de création de votre complément et testez-le localement.

Générateur Yeoman

Conditions préalables

• Node.js (la dernière version LTS) Visitez le siteNode.js pour télécharger et installer la version appropriée pour votre système d’exploitation.

• La dernière version deYeoman et du Générateur Yeoman Générateur de compléments Office. Pour installer ces outils globalement, exécutez la commande suivante via l’invite de commande.

  npm install -g yo generator-office
  

  Remarque

  Même si vous avez précédemment installé le générateur Yeoman, nous vous recommandons de mettre à jour votre package vers la dernière version de npm.

• Office connecté à un abonnement Microsoft 365 (y compris Office on the web).

  Remarque

  Si vous n’avez pas encore Office, vous pouvez bénéficier d’un abonnement Microsoft 365 E5 développeur par le biais du Programme pour les développeurs Microsoft 365. Pour plus d’informations, consultez le FAQ. Vous pouvez également vous inscrire à un essai gratuit de 1 mois ou acheter un plan Microsoft 365.

• Outlook 2016 ou version ultérieure sur Windows (connecté à un compte Microsoft 365), Outlook sur Mac, Outlook sur le web ou nouveau Outlook sur Windows (préversion).

Création du projet de complément

1. Exécutez la commande suivante pour créer un projet de complément à l’aide du générateur Yeoman. Un dossier qui contient le projet est ajouté au répertoire actif.

   yo office
   

   Remarque

   Lorsque vous exécutez la commande yo office, il est possible que vous receviez des messages d’invite sur les règles de collecte de données de Yeoman et les outils CLI de complément Office. Utilisez les informations fournies pour répondre aux invites comme vous l’entendez.

   Lorsque vous y êtes invité, fournissez les informations suivantes pour créer votre projet de complément.

   • Sélectionnez un type de projet - Office Add-in Task Pane project

   • Sélectionnez un type de script - JavaScript

   • Comment souhaitez-vous nommer votre complément ? - My Office Add-in

   • Quelle application client Office voulez-vous prendre en charge ? - Outlook

   

   Après avoir exécuté l’assistant, le générateur crée le projet et installe les composants Node de prise en charge.

   Remarque

   Si vous utilisez Node.js version 20.0.0 ou ultérieure, un avertissement peut s’afficher lorsque le générateur exécute l’installation indiquant que vous disposez d’un moteur non pris en charge. Nous travaillons sur un correctif pour cela. En attendant, l’avertissement n’affecte pas le générateur ou le projet que vous générez. Il peut donc être ignoré.

   Conseil

   Vous pouvez ignorer les instructions suivantes fournies par le générateur Yeoman une fois que le complément a été créé. Les instructions détaillées de cet article fournissent tous les conseils nécessaires à l’exécution de ce didacticiel.

2. Accédez au dossier racine du projet de l’application web.

   cd "My Office Add-in"
   

Explorer le projet

Le projet de complément que vous avez créé à l’aide du générateur Yeoman contient un exemple de code pour un complément de volet de tâches très simple.

• Le fichier ./manifest.xml du répertoire racine du projet définit les paramètres et fonctionnalités du complément.
• Le fichier ./src/taskpane/taskpane.html contient les balises HTML du volet Office.
• Le fichier ./src/taskpane/taskpane.css contient le style CSS appliqué au contenu du volet Office.
• Le fichier ./src/taskpane/taskpane.js contient le code d’API JavaScript pour Office qui facilite l’interaction entre le volet Office et Outlook.

Mettre à jour le code

1. Ouvrez votre projet dans VS Code ou votre éditeur de code préféré.

   Conseil

   Dans Windows, vous pouvez accéder au répertoire racine du projet via la ligne de commande, puis entrer code . pour ouvrir ce dossier dans VS Code. Sur Mac, vous devez ajouter la commande code au chemin d’accès avant de pouvoir utiliser cette commande pour ouvrir le dossier de projet dans VS Code.

2. Ouvrez le fichier ./src/taskpane/taskpane.html et remplacez l’élément main> entier< (dans l’élément <body>) par le balisage suivant. Ce nouveau balisage ajoute une étiquette à l’emplacement où le script dans ./src/taskpane/taskpane.js écrira des données.

   <main id="app-body" class="ms-welcome__main" style="display: none;">
       <h2 class="ms-font-xl"> Discover what Office Add-ins can do for you today! </h2>
       <p><label id="item-subject"></label></p>
       <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
           <span class="ms-Button-label">Run</span>
       </div>
   </main>
   

3. Dans votre éditeur de code, ouvrez le fichier ./src/taskpane/taskpane.js, puis ajoutez le code suivant à la fonction d’exécution . Ce code utilise l'API Office JavaScript pour obtenir une référence au message actuel et écrire la valeur de sa propriété objet dans le volet des tâches.

   // Get a reference to the current message
   const item = Office.context.mailbox.item;
   
   // Write message property value to the task pane
   document.getElementById("item-subject").innerHTML = "<b>Subject:</b> <br/>" + item.subject;
   

   Votre fichier taskpane.js doit maintenant contenir le code suivant.

   /*
    * Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
    * See LICENSE in the project root for license information.
    */
   
   /* global document, Office */
   
   Office.onReady((info) => {
     if (info.host === Office.HostType.Outlook) {
       document.getElementById("sideload-msg").style.display = "none";
       document.getElementById("app-body").style.display = "flex";
       document.getElementById("run").onclick = run;
     }
   });
   
   export async function run() {
     // Get a reference to the current message
     const item = Office.context.mailbox.item;
   
     // Write message property value to the task pane
     document.getElementById("item-subject").innerHTML = "<b>Subject:</b> <br/>" + item.subject;
   }
   

Essayez

Remarque

Les compléments Office doivent utiliser HTTPS, et non HTTP, même lorsque vous développez. Si vous êtes invité à installer un certificat après avoir exécuté l’une des commandes suivantes, acceptez l’invite pour installer le certificat fourni par le générateur Yeoman. Il se peut également que vous deviez exécuter votre invite de commande ou votre terminal en tant qu'administrateur pour que les modifications soient effectuées.

1. 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 et votre complément est chargé de manière indépendante.

   npm start
   

   Remarque

   Si votre complément n’a pas été automatiquement chargé de manière indépendante, suivez les instructions fournies dans Charger une version test des compléments Outlook pour charger manuellement une version test du complément dans Outlook.

2. Sur Outlook, affichez un message dans le volet de lectureou ouvrez le message dans sa propre fenêtre.

3. Choisissez l’onglet Accueil (ou l’onglet Message si vous avez ouvert le message dans une nouvelle fenêtre), puis choisissez le bouton Afficher le volet Des tâches sur le ruban pour ouvrir le volet Office du complément.

   

4. Lorsque la boîte de dialogue WebView Stop On Load apparaît, sélectionnez OK.

   Remarque

   Si vous sélectionnez Annuler, la boîte de dialogue ne s’affiche plus lors de l’exécution de cette instance du complément. Toutefois, si vous redémarrez votre complément, la boîte de dialogue s’affichera à nouveau.

5. Faites défiler vers le bas du volet Office et sélectionnez le lien Exécuter pour écrire l’objet du message dans le volet Office.

   

   

Étapes suivantes

Félicitations, vous avez créé votre premier complément de volet de tâches Outlook ! Ensuite, découvrez les fonctionnalités d’un complément Outlook et créez-en un plus complexe en suivant le didacticiel pour complément Outlook.

Visual Studio

Configuration requise

• Visual Studio 2019 ou version ultérieure avec la charge de travail développement Office/SharePoint installée

  Remarque

  Si vous avez déjà installé Visual Studio 2019 ou version ultérieure, utilisez la Visual Studio Installer pour vous assurer que la charge de travail de développement Office/SharePoint est installée.

• Office connecté à un abonnement Microsoft 365 (y compris Office on the web).

Création du projet de complément

1. Dans la barre de menu de Visual Studio, choisissez successivement Fichier>Nouveau>Projet.

2. Dans la liste des types de projets sous Visual C# ou Visual Basic, développez Office/SharePoint, choisissez Compléments, puis Complément web Outlook pour le type de projet.

3. Nommez le projet, puis cliquez sur OK.

4. Visual Studio crée une solution et ses deux projets apparaissent dans l’Explorateur de solutions. Le fichier MessageRead.html s’ouvre dans Visual Studio.

Explorer la solution Visual Studio

Quand vous arrivez au bout de l’Assistant, Visual Studio crée une solution qui contient deux projets.

Project	Description
Projet de complément	Contient uniquement un fichier manifeste XML contenant tous les paramètres qui décrivent votre complément. Ces paramètres aident l’application Office à déterminer le moment où votre complément doit être activé et l’emplacement où il doit apparaître. Visual Studio génère le contenu de ce fichier pour vous permettre d’exécuter le projet et d’utiliser votre complément immédiatement. Vous pouvez modifier ces paramètres à tout moment en modifiant le fichier XML.
Projet d’application web	Contient les pages de contenu de votre complément, notamment tous les fichiers et références de fichiers dont vous avez besoin pour développer des pages HTML et JavaScript compatibles avec Office. Pendant que vous développez votre complément, Visual Studio héberge l’application web sur votre serveur IIS (Internet Information Services) local. Lorsque vous êtes prêt à publier le complément, vous devez déployer ce projet d’application web sur un serveur web.

Mise à jour du code

1. MessageRead.html spécifie le code HTML qui s’affichera dans le volet Office du complément. Dans MessageRead.html, remplacez l’élément <body> par le balisage suivant et enregistrez le fichier.

   <body class="ms-font-m ms-welcome">
       <div class="ms-Fabric content-main">
           <h1 class="ms-font-xxl">Message properties</h1>
           <table class="ms-Table ms-Table--selectable">
               <thead>
                   <tr>
                       <th>Property</th>
                       <th>Value</th>
                   </tr>
               </thead>
               <tbody>
                   <tr>
                       <td><strong>Id</strong></td>
                       <td class="prop-val"><code><label id="item-id"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>Subject</strong></td>
                       <td class="prop-val"><code><label id="item-subject"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>Message Id</strong></td>
                       <td class="prop-val"><code><label id="item-internetMessageId"></label></code></td>
                   </tr>
                   <tr>
                       <td><strong>From</strong></td>
                       <td class="prop-val"><code><label id="item-from"></label></code></td>
                   </tr>
               </tbody>
           </table>
       </div>
   </body>
   

2. Ouvrez le fichier MessageRead.js à la racine du projet d’application web. Ce fichier spécifie le script pour le complément. Remplacez tout le contenu par le code suivant, puis enregistrez le fichier.

   'use strict';
   
   (function () {
   
       Office.onReady(function () {
           // Office is ready
           $(document).ready(function () {
               // The document is ready
               loadItemProps(Office.context.mailbox.item);
           });
       });
   
       function loadItemProps(item) {
           // Write message property values to the task pane
           $('#item-id').text(item.itemId);
           $('#item-subject').text(item.subject);
           $('#item-internetMessageId').text(item.internetMessageId);
           $('#item-from').html(item.from.displayName + " <" + item.from.emailAddress + ">");
       }
   })();
   

3. Ouvrez le fichier MessageRead.css à la racine du projet d’application web. Ce fichier spécifie les styles personnalisés pour le complément. Remplacez tout le contenu par le code suivant, puis enregistrez le fichier.

   html,
   body {
       width: 100%;
       height: 100%;
       margin: 0;
       padding: 0;
   }
   
   td.prop-val {
       word-break: break-all;
   }
   
   .content-main {
       margin: 10px;
   }
   

Mise à jour du manifeste

1. Ouvrez le fichier manifeste XML dans le projet de complément. Ce fichier définit les paramètres et les fonctionnalités du complément.

2. L’élément< ProviderName> a une valeur d’espace réservé. Remplacez-le par votre nom.

3. L’attribut DefaultValue de l’élément <DisplayName> a un espace réservé. Remplacez-le par My Office Add-in.

4. L’attribut DefaultValue de l’élément <Description> a un espace réservé. Remplacez-le par My First Outlook add-in.

5. Enregistrez le fichier.

   ...
   <ProviderName>John Doe</ProviderName>
   <DefaultLocale>en-US</DefaultLocale>
   <!-- The display name of your add-in. Used on the store and various places of the Office UI such as the add-ins dialog. -->
   <DisplayName DefaultValue="My Office Add-in" />
   <Description DefaultValue="My First Outlook add-in"/>
   ...
   

Try it out

1. À l’aide de Visual Studio, testez le complément Outlook nouvellement créé en appuyant sur F5 ou en choisissant le bouton Démarrer . Le complément est hébergé localement sur IIS.

2. Dans la boîte de dialogue Se connecter à un compte de messagerie Exchange , entrez l’adresse e-mail et le mot de passe de votre compte Microsoft, puis choisissez Se connecter. Lorsque la page de connexion Outlook.com s’ouvre dans un navigateur, connectez-vous à votre compte de courrier avec les mêmes informations d’identification que vous avez entrées précédemment.

   Remarque

   Si la boîte de dialogue Se connecter à un compte de messagerie Exchange vous invite à vous connecter à plusieurs reprises ou si vous recevez une erreur indiquant que vous n’êtes pas autorisé, l’authentification de base peut être désactivée pour les comptes de votre locataire Microsoft 365. Pour tester ce complément, essayez de vous reconnecter après avoir défini la propriété Utiliser l’authentification multifacteur sur True dans la section Déploiement de la boîte de dialogue propriétés du projet de complément web, ou connectez-vous à l’aide d’un compte Microsoft à la place.

3. Votre boîte aux lettres s’ouvre dans Outlook sur le web. Sélectionnez ou ouvrez un message.

   Conseil

   Vous pouvez également tester le complément dans Outlook sur Windows tant que le serveur IIS est en cours d’exécution.

4. Dans le message, accédez à la barre d’action, puis sélectionnez Applications.

   

5. Dans la liste des compléments, sélectionnez Mon complément Office, puis choisissez Afficher le volet Office.

   

6. Affichez les propriétés du message sélectionné à partir du volet Office qui s’ouvre.

   

   Remarque

   Si le volet Office n’est pas chargé, essayez de l’ouvrir dans un navigateur sur le même ordinateur.

Étapes suivantes

Félicitations, vous avez créé votre premier complément de volet de tâches Outlook ! Ensuite, en savoir plus sur la création de compléments Office avec Visual Studio.

Résolution des problèmes

• Vérifiez que votre environnement est prêt pour le développement Office en suivant les instructions fournies dans Configurer votre environnement de développement.

• L’étape automatique npm install effectuée par Yo Office peut échouer. Si vous voyez des erreurs lors de la tentative d’exécution npm start, accédez au dossier de projet nouvellement créé dans une invite de commandes et exécutez npm installmanuellement . Pour plus d’informations sur Yo Office, voir Créer des projets de complément Office à l’aide du générateur Yeoman.

• Si votre complément affiche une erreur (par exemple, « Ce complément n’a pas pu être démarré. Fermez cette boîte de dialogue pour ignorer le problème ou cliquez sur « Redémarrer » pour réessayer. ») Lorsque vous appuyez sur F5 ou choisissez Déboguer>Démarrer le débogage dans Visual Studio, consultez Déboguer les compléments Office dans Visual Studio pour obtenir d’autres options de débogage.

• Certains exemples de code utilisent ES6 JavaScript. Cela n’est pas compatible avec les versions antérieures d’Office qui utilisent le moteur de navigateur Trident (Internet Explorer 11). Pour plus d’informations sur la prise en charge de ces plateformes dans votre complément, consultez Prise en charge des vues web Microsoft plus anciennes et des versions d’Office. Si vous n’avez pas encore d’abonnement Microsoft 365 à utiliser pour le développement, vous pouvez bénéficier d’un abonnement Microsoft 365 E5 développeur par le biais du Programme pour les développeurs Microsoft 365. Pour plus d’informations, consultez le FAQ. Vous pouvez également vous inscrire à un essai gratuit de 1 mois ou acheter un plan Microsoft 365.

Si le message d’erreur « Désolé... nous ne pouvons pas ouvrir ce complément à partir de localhost » s’affiche dans le volet Office, suivez les étapes décrites dans l’article résolution des problèmes.

Exemples de code

• Complément Outlook « Hello monde » : découvrez comment créer un complément Office simple avec uniquement un manifeste, une page web HTML et un logo.

Voir aussi

• Manifeste XML des compléments Office
• Utilisation de Visual Studio Code pour publier