Partager via

Utiliser l’interface utilisateur Fluent React dans les compléments Office

  • Article

Fluent UI React est l’infrastructure frontale JavaScript open source officielle conçue pour créer des expériences qui s’intègrent parfaitement dans un large éventail de produits Microsoft, y compris les applications Microsoft 365. Il fournit des composants robustes, à jour, accessibles et basés sur React, qui sont hautement personnalisables à l'aide de CSS-in-JS.

Remarque

Cet article décrit l’utilisation de l’interface utilisateur Fluent React dans le contexte des compléments Office. Toutefois, il est également utilisé dans un large éventail d’applications et d’extensions Microsoft 365. Pour plus d’informations, consultez Fluent UI React et le référentiel d’open source web de l’interface utilisateur Fluent.

Cet article explique comment créer un complément créé avec React et qui utilise des composants React de l’interface utilisateur Fluent.

Création d’un projet de complément

Vous allez utiliser le générateur Yeoman pour les compléments Office pour créer un projet de complément qui utilise React.

Remarque

Les compléments basés sur React créés avec le générateur utilisent l’interface utilisateur Fluent React V9. Cette version ne prend pas en charge la vue web Trident (IE). Si les utilisateurs de votre complément ont des versions d’Office qui nécessitent Trident, utilisez l’un des exemples dans Office-Add-ins-Fluent-React-version-8 au lieu de cet article. Pour plus d’informations sur les versions d’Office qui utilisent Trident, voir Navigateurs et contrôles d’affichage web utilisés par les compléments Office.

Installez les composants requis

  • 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éez le projet

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 : Spécifiez Office Add-in Task Pane project using React framework.
  • Choisissez un type de script : Spécifiez ou TypeScriptJavaScript.
  • Comment souhaitez-vous nommer votre complément ? Précisez My Office Add-in.
  • Quelle application client Office voulez-vous prendre en charge ? Spécifiez l’un des hôtes. (Les captures d’écran de cet article utilisent Word. L’exécution du projet pour la première fois est plus facile si vous sélectionnez Excel, PowerPointou Word. Voir Essayer.)

Voici un exemple.

Générateur Yeoman dans une interface de ligne de commande avec les invites et les réponses.

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

L’interface utilisateur Fluent React v9 ou ultérieure n’est pas prise en charge avec les contrôles de vue web Trident (IE) ou EdgeHTML (Edge Legacy). Si votre version d’Office utilise l’une ou l’autre de ces options, le volet Office du complément généré par Yo Office contient simplement un message pour mettre à niveau votre version d’Office. Pour plus d’informations, voir Navigateurs et contrôles d’affichage web utilisés par les compléments Office.

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. Si vous souhaitez explorer les composants de votre projet de complément, ouvrez le projet dans votre éditeur de code et passez en revue les fichiers suivants. Les extensions de nom de fichier dépendent de la langue que vous choisissez. Les extensions TypeScript sont entre parenthèses. 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. Pour en savoir plus sur le fichier manifest.xml , voir Compléments Office avec le manifeste du complément uniquement.
  • Le fichier ./src/taskpane/taskpane.html contient le balisage HTML du volet Office et charge la bibliothèque JavaScript Office. Il teste également si le contrôle webview prend en charge l’interface utilisateur Fluent React v9 et affiche un message spécial si ce n’est pas le cas.
  • Le fichier ./src/taskpane/index.jsx (tsx) est le composant racine React. Il charge React et l’interface utilisateur Fluent React, garantit que la bibliothèque JavaScript Office a été chargée et applique le thème défini par Fluent.
  • Le fichier ./src/taskpane/office-document.js (ts) contient le code de l’API JavaScript Office qui facilite l’interaction entre le volet Office et l’application cliente Office.
  • Le dossier ./src/taskpane/components/ contient les fichiers de composant React *.jss (tsx) qui créent l’interface utilisateur.

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.

    • Si c’est la première fois que vous développez un complément Office sur votre ordinateur, vous pouvez être invité dans la ligne de commande à accorder à Microsoft Edge WebView une exemption de bouclage (« Autoriser le bouclage localhost pour Microsoft Edge WebView ? »). Lorsque vous y êtes invité, entrez Y pour autoriser l’exemption. Notez que vous aurez besoin de privilèges d’administrateur pour autoriser l’exemption. Une fois autorisé, vous ne devez pas être invité à bénéficier d’une exemption lorsque vous chargez une version test des compléments Office à l’avenir (sauf si vous supprimez l’exemption de votre ordinateur). Pour plus d’informations, consultez « Nous ne pouvons pas ouvrir ce complément à partir de localhost » lors du chargement d’un complément Office ou de l’utilisation de Fiddler.

      Invite dans la ligne de commande pour autoriser Microsoft Edge WebView à bénéficier d’une exemption de bouclage.

    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, exécutez la commande suivante dans le répertoire racine de votre projet. Cela démarre le serveur web local et ouvre l’application hôte Office avec votre complément chargé.

      npm start

      Remarque

      Si vous testez votre complément dans Outlook, npm start charge la version test du complément sur les clients de bureau et web Outlook. Pour plus d’informations sur la façon de charger une version test des compléments dans Outlook, voir Charger une version test des compléments Outlook.

    • Pour tester votre complément dans Excel, Word ou PowerPoint 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. 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.

    Remarque

    Si c’est la première fois que vous avez chargé un complément Office sur votre ordinateur (ou la première fois depuis plus d’un mois), vous êtes d’abord invité à supprimer un ancien certificat, puis à en installer un nouveau. Acceptez les deux invites.

  3. Une invite WebView Stop On Load s’affiche. Sélectionnez OK.

  4. Si le volet Office « Mon complément Office » n’est pas déjà ouvert, choisissez l’onglet Accueil , puis choisissez le bouton Afficher le volet Office sur le ruban pour ouvrir le volet Office du complément.

    Remarque

    Si vous testez votre complément dans Outlook, créez un message. Ensuite, accédez à l’onglet Message et choisissez Afficher le volet Des tâches dans le ruban pour ouvrir le volet Office du complément.

  5. Entrez du texte dans la zone de texte, puis sélectionnez Insérer du texte.

    Texte personnalisé inséré dans le document après avoir sélectionné le bouton Insérer dans le volet Office du complément.

  6. Lorsque vous êtes prêt à arrêter le serveur de développement et à désinstaller le complément, exécutez la commande suivante.

    npm stop

Migrer vers Fluent UI React v9

Si vous disposez déjà d’un complément qui implémente une version antérieure de Fluent UI React, nous vous recommandons de migrer vers Fluent UI v9. Pour obtenir des conseils sur le processus de migration, consultez Prise en main de la migration vers v9.

Résolution des problèmes

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

Voir aussi