Créer des projets de complément Office à l’aide du générateur Yeoman

Le générateur Yeoman pour les compléments Office (également appelé « Yo Office ») est un outil en ligne de commande interactif Node.js qui crée des projets de développement de complément Office. Nous vous recommandons d’utiliser cet outil pour créer des projets de complément, sauf lorsque vous souhaitez que le code côté serveur du complément se trouve dans un . Langage basé sur NET (par exemple, C# ou VB.Net) ou vous souhaitez que le complément soit hébergé dans Internet Information Server (IIS). Dans l’une des deux dernières situations, utilisez Visual Studio pour créer le complément.

Remarque

Les compléments Office peuvent également être créés avec le Kit de ressources Teams (version préliminaire). Pour plus d’informations sur la façon de procéder et sur les limitations, voir Créer des projets de complément Office à l’aide du Kit de ressources Teams (préversion) .

Les projets créés par l’outil présentent les caractéristiques suivantes.

• Ils ont une configuration npm standard qui inclut un fichier package.json .
• Ils incluent plusieurs scripts utiles pour générer le projet, démarrer le serveur, charger une version test du complément dans Office et d’autres tâches.
• Ils utilisent webpack comme bundler et exécuteur de tâches de base.
• En mode développement, ils sont hébergés sur localhost par webpack-dev-server basé sur Node.js, une version orientée développement du serveur express qui prend en charge le rechargement à chaud et la recompilation en cas de modification.
• Par défaut, toutes les dépendances sont installées par l’outil, mais vous pouvez reporter l’installation avec un argument de ligne de commande.
• Ils incluent un manifeste de complément complet.
• Ils disposent d’un complément de niveau « Hello World » qui est prêt à être exécuté dès que l’outil est terminé.
• Ils incluent un polyfill et un transpileur configuré pour transpiler TypeScript, ainsi que les versions récentes de JavaScript, en JavaScript ES5. Ces fonctionnalités garantissent que le complément est pris en charge dans tous les runtimes webview dans lesquels les compléments Office peuvent s’exécuter, y compris Trident (Internet Explorer).

Conseil

Si vous souhaitez vous écarter considérablement de ces choix, comme l’utilisation d’un autre exécuteur de tâches ou d’un autre serveur, nous vous recommandons de choisir l’option Manifeste uniquement lorsque vous exécutez l’outil.

Installer le générateur

Remarque

Si vous n’êtes pas familiarisé avec les nœuds.js ou npm, vous devez commencer par configuration de votre environnement de développement.

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

Utiliser l’outil

Démarrez l’outil avec la commande suivante dans une invite système (et non une fenêtre bash). Cela crée un projet dans un nouveau dossier dans le répertoire actif.

yo office 

Un grand nombre de chargements sont nécessaires, donc 20 secondes peuvent être nécessaires avant que l’outil ne démarre. L’outil vous pose une série de questions. Pour certains, il vous suffit de taper une réponse à l’invite. Pour les autres, vous recevez une liste de réponses possibles. Si vous recevez une liste, sélectionnez-en une, puis sélectionnez Entrée.

La première question vous invite à choisir entre plusieurs types de projets. Les options disponibles sont les suivantes :

• Projet du volet Office de complément Office
• Projet du volet Office de complément Office utilisant React framework
• Fonctions personnalisées Excel à l’aide d’un runtime partagé
• Fonctions personnalisées Excel à l’aide d’un runtime JavaScript uniquement
• Projet du volet Office de complément Office prenant en charge l’authentification unique
• Complément Outlook avec le manifeste unifié pour Microsoft 365 (préversion)
• Projet de complément Office contenant uniquement le manifeste

Remarque

• Le manifeste unifié est en préversion et est pris en charge uniquement sur Outlook sur Windows. Il n’est pas encore pris en charge pour un complément de production.
• Le projet de complément Office contenant l’option manifeste uniquement produit un projet qui contient un manifeste de complément de base et une structure minimale. Pour plus d’informations sur l’option, consultez Option manifeste uniquement.

La question suivante vous demande de choisir entre TypeScript et JavaScript. (Cette question est ignorée si vous avez choisi l’option manifeste uniquement dans la question précédente.)

Vous êtes ensuite invité à donner un nom au complément. Le nom que vous spécifiez sera utilisé dans le manifeste du complément, mais vous pourrez le modifier ultérieurement. Il s’agit également du nom du dossier pour le projet.

Vous êtes ensuite invité à choisir l’application Office dans laquelle le complément doit s’exécuter. Il existe six applications possibles : Excel, OneNote, Outlook, PowerPoint, Project et Word. Vous devez en choisir un seul, mais vous pouvez modifier le manifeste ultérieurement pour prendre en charge les applications Office supplémentaires. L’exception est Outlook. Un manifeste qui prend en charge Outlook ne peut prendre en charge aucune autre application Office.

Une fois que vous avez répondu à cette question, le générateur crée le projet et installe les dépendances. Vous pouvez voir des messages WARN dans la sortie npm à l’écran. Vous pouvez les ignorer. Vous pouvez également voir des messages indiquant que des vulnérabilités ont été détectées. Vous pouvez les ignorer pour l’instant, mais vous devrez les corriger avant que votre complément ne soit publié en production. Pour plus d’informations sur la résolution des vulnérabilités, ouvrez votre navigateur et recherchez « vulnérabilité npm ».

Si la création réussit, un message Félicitations ! s’affiche dans la fenêtre de commande, suivi des étapes suivantes suggérées. (Si vous utilisez le générateur dans le cadre d’un démarrage rapide ou d’un didacticiel, ignorez les étapes suivantes dans la fenêtre de commande et poursuivez avec les instructions de l’article.)

Conseil

Si vous souhaitez créer la structure d’un projet de complément Office, mais reporter l’installation des dépendances, ajoutez l’option --skip-install à la yo office commande . Voici un exemple de code.

yo office --skip-install

Lorsque vous êtes prêt à installer les dépendances, accédez au dossier racine du projet dans une invite de commandes et entrez npm install.

Avertissement

Si vous choisissez un projet de volet office de complément Office prenant en charge l’authentification unique et TypeScript, et que vous utilisez une version Node.js supérieure à 18.16.0, un bogue dans Node.js endommage le fichier <projet root>\src\middle-tier\ssoauth-helper.ts . Pour résoudre ce problème, copiez le contenu du fichier à partir du dépôt , ssoauth-helper.ts, sur le contenu du fichier dans le projet généré.

Option Manifeste uniquement

Cette option crée uniquement un manifeste pour un complément. Le projet résultant n’a pas de complément Hello World, aucun des scripts ou aucune des dépendances. Utilisez cette option dans les scénarios suivants.

• Vous souhaitez utiliser des outils différents de ceux qu’un projet de générateur Yeoman installe et configure par défaut. Par exemple, vous souhaitez utiliser un autre bundler, un transpileur, un exécuteur de tâches ou un serveur de développement différent.
• Vous souhaitez utiliser une infrastructure de développement d’applications web, autre que React, telle que Vue.

Pour obtenir un exemple d’utilisation du générateur avec l’option manifeste uniquement, voir Utiliser Vue pour générer un complément du volet Office Excel.

Utiliser les paramètres de ligne de commande

Vous pouvez également ajouter des paramètres à la yo office commande . Les deux plus courantes sont :

• yo office --details: cette opération génère une brève aide sur tous les autres paramètres de ligne de commande.
• yo office --skip-install: cela empêche le générateur d’installer les dépendances.

Pour obtenir des informations détaillées sur les paramètres de ligne de commande, consultez le fichier lisez-moi du générateur dans le générateur Yeoman pour les compléments Office.

Résolution des problèmes

Si vous rencontrez des problèmes lors de l’utilisation de l’outil, la première étape consiste à le réinstaller pour vous assurer que vous disposez de la dernière version. (Pour plus d’informations, consultez Installer le générateur .) Si cela ne résout pas le problème, recherchez l’outil dans les problèmes du dépôt GitHub pour voir si quelqu’un d’autre a rencontré le même problème et trouvé une solution. Si personne n’en a, créez un problème.