Créer votre premier complément du volet des tâches de Word

Cet article décrit comment créer un complément du volet des tâches de Word.

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.

Création du projet de complément

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.

• Choisissez un type de projet :Office Add-in Task Pane project
• Choisissez un type de script :JavaScript
• Que voulez-vous nommer votre complément ?My Office Add-in
• Quelle application cliente Office souhaitez-vous prendre en charge ?Word

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.

Explorer le projet

Le projet de complément que vous avez créé avec le générateur Yeoman contient un exemple de code pour un complément de volet Office de base. Pour explorer les composants de votre projet de complément, ouvrez le projet dans votre éditeur de code et passez en revue les fichiers répertoriés ci-dessous. Lorsque vous êtes prêt à tester votre complément, passez à la section suivante.

• 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 des tâches et l’application cliente Office.

Essayez

1. Accédez au dossier racine du projet.

   cd "My Office Add-in"
   

2. Pour démarrer le serveur web local et charger indépendamment votre complément, procédez comme suit.

   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.

   Conseil

   Si vous testez votre complément sur Mac, exécutez la commande suivante avant de continuer. Lorsque vous exécutez cette commande, le serveur web local démarre.

   npm run dev-server
   

   • Pour tester votre complément dans Word, 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 Word avec votre complément chargé.

     npm start
     

   • Pour tester votre complément dans Word sur un navigateur, 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. Remplacez « {url} » par l’URL d’un document Word sur votre OneDrive ou une bibliothèque SharePoint sur laquelle vous avez des autorisations.

     Remarque

     Si vous développez sur un Mac, placez le {url} entre guillemets simples. Ne le faites pas sur Windows.

     npm run start:web -- --document {url}
     

     Les éléments suivants sont des exemples.

     • npm run start:web -- --document https://contoso.sharepoint.com/:t:/g/EZGxP7ksiE5DuxvY638G798BpuhwluxCMfF1WZQj3VYhYQ?e=F4QM1R
     • npm run start:web -- --document https://1drv.ms/x/s!jkcH7spkM4EGgcZUgqthk4IK3NOypVw?e=Z6G1qp
     • npm run start:web -- --document https://contoso-my.sharepoint-df.com/:t:/p/user/EQda453DNTpFnl1bFPhOVR0BwlrzetbXvnaRYii2lDr_oQ?e=RSccmNP

     Si votre complément ne charge pas de version test dans le document, chargez-le manuellement en suivant les instructions fournies dans Charger manuellement une version test des compléments pour Office sur le Web.

3. Dans Word, si le volet Office « Mon complément Office » n’est pas déjà ouvert, ouvrez un nouveau document, choisissez l’onglet Accueil, puis choisissez le bouton Afficher le volet Office dans le ruban pour ouvrir le volet Office du complément.

   

4. En bas du volet Office, sélectionnez le lien Exécuter pour ajouter le texte en police de couleur bleue « Hello World » au document.

   

Étapes suivantes

Félicitations, vous avez créé un complément du volet des tâches de Word ! Maintenant, découvrez les fonctionnalités d’un complément Word et créez un complément plus complexe en suivant le didacticiel dédié.

Didacticiel sur les compléments Word

Visual Studio

Configuration requise

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

  Remarque

  Si vous avez déjà installé Visual Studio, utilisez le programme d'installation de Visual Studio 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 Visual Studio, choisissez Créer un nouveau projet.

2. À l’aide de la zone de recherche, entrez complément. Choisissez Complément web Word, puis sélectionnez Suivant.

3. Nommez votre projet et sélectionnez Créer.

4. Visual Studio crée une solution et ses deux projets apparaissent dans l’Explorateur de solutions. Le fichier Home.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. Modifiez 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 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. Home.html spécifie le code HTML qui s’affichera dans le volet Office du complément. Dans Home.html, remplacez l’élément <body> par le balisage suivant et enregistrez le fichier.

   <body>
       <div id="content-header">
           <div class="padding">
               <h1>Welcome</h1>
           </div>
       </div>
       <div id="content-main">
           <div class="padding">
               <p>Choose the buttons below to add boilerplate text to the document by using the Word JavaScript API.</p>
               <br />
               <h3>Try it out</h3>
               <button id="emerson">Add quote from Ralph Waldo Emerson</button>
               <br /><br />
               <button id="checkhov">Add quote from Anton Chekhov</button>
               <br /><br />
               <button id="proverb">Add Chinese proverb</button>
           </div>
       </div>
       <br />
       <div id="supportedVersion"/>
   </body>
   

2. Ouvrez le fichier Home.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.
               // Use this to check whether the API is supported in the Word client.
               if (Office.context.requirements.isSetSupported('WordApi', '1.1')) {
                   // Do something that is only available via the new APIs.
                   $('#emerson').on("click", insertEmersonQuoteAtSelection);
                   $('#checkhov').on("click", insertChekhovQuoteAtTheBeginning);
                   $('#proverb').on("click", insertChineseProverbAtTheEnd);
                   $('#supportedVersion').html('This code is using Word 2016 or later.');
               } else {
                   // Lets you know that this code will not work with your version of Word.
                   $('#supportedVersion').html('This code requires Word 2016 or later.');
               }
           });
       });
   
       async function insertEmersonQuoteAtSelection() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document.
               const thisDocument = context.document;
   
               // Queue a command to get the current selection.
               // Create a proxy range object for the selection.
               const range = thisDocument.getSelection();
   
               // Queue a command to replace the selected text.
               range.insertText('"Hitch your wagon to a star." - Ralph Waldo Emerson\n', Word.InsertLocation.replace);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from Ralph Waldo Emerson.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   
       async function insertChekhovQuoteAtTheBeginning() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document body.
               const body = context.document.body;
   
               // Queue a command to insert text at the start of the document body.
               body.insertText('"Knowledge is of no value unless you put it into practice." - Anton Chekhov\n', Word.InsertLocation.start);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from Anton Chekhov.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   
       async function insertChineseProverbAtTheEnd() {
           await Word.run(async (context) => {
   
               // Create a proxy object for the document body.
               const body = context.document.body;
   
               // Queue a command to insert text at the end of the document body.
               body.insertText('"To know the road ahead, ask those coming back." - Chinese proverb\n', Word.InsertLocation.end);
   
               // Synchronize the document state by executing the queued commands,
               // and return a promise to indicate task completion.
               await context.sync();
               console.log('Added a quote from a Chinese proverb.');
           })
           .catch(function (error) {
               console.log('Error: ' + JSON.stringify(error));
               if (error instanceof OfficeExtension.Error) {
                   console.log('Debug info: ' + JSON.stringify(error.debugInfo));
               }
           });
       }
   })();
   

3. Ouvrez le fichier Home.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.

   #content-header {
       background: #2a8dd4;
       color: #fff;
       position: absolute;
       top: 0;
       left: 0;
       width: 100%;
       height: 80px;
       overflow: hidden;
   }
   
   #content-main {
       background: #fff;
       position: fixed;
       top: 80px;
       left: 0;
       right: 0;
       bottom: 0;
       overflow: auto;
   }
   
   .padding {
       padding: 15px;
   }
   

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 possède une valeur d’espace réservé. Remplacez-le par votre nom.

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

4. L’attribut DefaultValue de l’élément Description possède un espace réservé. Remplacez-le par A task pane add-in for Word.

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-in's dialog. -->
   <DisplayName DefaultValue="My Office Add-in" />
   <Description DefaultValue="A task pane add-in for Word."/>
   ...
   

Essayez

1. À l’aide de Visual Studio, testez le complément Word nouvellement créé en appuyant sur F5 ou en choisissant Déboguer>Démarrer le débogage pour lancer Word avec le bouton Afficher le complément du volet Tâches affiché sur le ruban. Le complément est hébergé localement sur IIS.

2. Dans Word, si le volet Office du complément n’est pas déjà ouvert, choisissez l’onglet Accueil, puis le bouton Afficher le volet Des tâches dans le ruban pour ouvrir le volet Office du complément. (Si vous utilisez une version perpétuelle avec licence en volume d’Office 2016 ou une version antérieure, les boutons personnalisés ne sont pas pris en charge. Au lieu de cela, le volet Office s’ouvre immédiatement.)

   

3. Dans le volet Office, choisissez l’un des boutons pour ajouter du texte réutilisable dans le document.

   

Remarque

Pour voir la sortie console.log, vous devrez disposer d’un ensemble distinct d’outils de développement dédiés à une console JavaScript. Pour en savoir plus sur les outils F12 et les Outils de développement Microsoft Edge, consultez Déboguer des compléments à l’aide des outils de développement pour Internet Explorer, Déboguer des compléments à l’aide des outils de développement pour Edge Legacy, ou Déboguer les compléments à l’aide des outils de développement dans Microsoft Edge (basé sur Chromium).

Étapes suivantes

Félicitations, vous avez créé un complément du volet des tâches de Word ! Ensuite, pour en savoir plus sur le développement de compléments Office avec Visual Studio, passez à l’article suivant.

Développement 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.

Exemples de code

• Word complément « 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

• Vue d’ensemble de la plateforme des compléments Office
• Développement de compléments Office
• Présentation des compléments Word
• Exemples de code pour les compléments Word
• Référence d’API JavaScript pour Word
• Utilisation de Visual Studio Code pour publier