Configurer votre complément Office pour utiliser un runtime partagé

Vous pouvez configurer votre complément Office pour exécuter tout son code dans un runtime partagé unique. Vous pouvez ainsi améliorer la coordination dans votre complément et accéder aux DOM et CORS à partir de toutes les parties de votre complément. Il active également des fonctionnalités supplémentaires telles que l’exécution d’un code lors de l’ouverture d’un document, ou l’activation et la désactivation des boutons du ruban. Si vous voulez configurer votre complément pour utiliser un runtime partagé, suivez les instructions contenues dans cet article.

Création du projet de complément

Si vous démarrez un nouveau projet, utilisez le Générateur Yeoman pour compléments Office pour créer le projet de complément Excel, PowerPoint ou Word.

Exécutez la commande yo office --projectType taskpane --name "my office add in" --host <host> --js true, où <host> est l’une des valeurs suivantes.

• excel
• powerpoint
• word

Vous pouvez utiliser différentes options pour les options de ligne de commande --projecttype, --name et --js. Pour obtenir la liste complète des options, consultez Générateur Yeoman pour compléments Office.

Le générateur crée le projet et installe les composants de nœud de la prise en charge. Vous pouvez également utiliser les étapes décrites dans cet article pour mettre à jour un projet Visual afin d’utiliser le runtime partagé. Toutefois, vous devrez peut-être mettre à jour les schémas XML pour le manifeste. Pour plus d’informations, consultez Résoudre les erreurs de développement avec les compléments Office.

Configurer le manifeste

Procédez comme suit pour configurer un projet nouveau ou existant de manière à utiliser un runtime partagé. Ces étapes supposent que vous avez créé votre projet à l’aide du générateur Yeoman pour compléments Office.

1. Démarrez Visual Studio Code, puis ouvrez votre projet de complément.

2. Ouvrez le fichier manifest.xml.

3. Pour un complément Excel ou PowerPoint, mettez à jour la section des conditions requises pour inclure le runtime partagé. Veillez à supprimer la condition requise CustomFunctionsRuntime si elle est présente. Le XML s’affiche comme suit.

   <Hosts>
     <Host Name="Workbook"/>
   </Hosts>
   <Requirements>
     <Sets DefaultMinVersion="1.1">
       <Set Name="SharedRuntime" MinVersion="1.1"/>
     </Sets>
   </Requirements>
   <DefaultSettings>
   

4. Recherchez la <section VersionOverrides> et ajoutez la section Runtimes> suivante<. La durée de vie doit être longue afin que votre code de complément puisse s’exécuter même quand le volet Office est fermé. La valeur resid est Taskpane.Url qui se réfère à l’emplacement du fichier taskpane.html spécifiée dans la section <bt:Urls> près du bas du fichier manifest.xml.

   Importante

   Le runtime partagé ne se charge pas si utilise des resid valeurs différentes dans le manifeste. Si vous remplacez la valeur par quelque chose d’autre que Taskpane.Url, veillez à modifier également la valeur dans tous les emplacements indiqués dans les étapes suivantes de cet article.

   En outre, la <section Runtimes> doit être entrée après l’élément <Host> dans l’ordre exact indiqué dans le code XML suivant.

   <VersionOverrides ...>
     <Hosts>
       <Host ...>
         <Runtimes>
           <Runtime resid="Taskpane.Url" lifetime="long" />
         </Runtimes>
       ...
       </Host>
   

5. Si vous avez généré un complément Excel avec des fonctions personnalisées, recherchez l’élément <Page> . Puis remplacez l’emplacement de la source Functions.Page.Url par TaskPane.Url.

   <AllFormFactors>
   ...
   <Page>
     <SourceLocation resid="Taskpane.Url"/>
   </Page>
   ...
   

6. Recherchez la <balise FunctionFile> et remplacez commands.Urlresid par Taskpane.Url. Notez que si vous n’avez pas de commandes d’action, vous n’aurez pas d’entrée <FunctionFile> et pouvez ignorer cette étape.

   </GetStarted>
   ...
   <FunctionFile resid="Taskpane.Url"/>
   ...
   

7. Enregistrez le fichier manifest.xml.

Configurer le fichier webpack.config.js

Le fichier webpack.config.js générera plusieurs chargeurs runtime. Vous devez le modifier pour charger uniquement le runtime partagé via le fichier taskpane.html .

1. Démarrez Visual Studio Code et ouvrez le projet de complément que vous avez généré.

2. Ouvrez le fichier webpack.config.js.

3. Si votre fichier webpack.config.js a le code plug-in functions.html, supprimez-le.

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

4. Si votre fichier webpack.config.js a le code plug-in commands.html, supprimez-le.

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

5. Si votre projet utilisait les blocs fonctions ou commandes, ajoutez-les à la liste des blocs comme illustré par la suite (le code suivant sert si votre projet utilisait les deux blocs).

     new HtmlWebpackPlugin({
       filename: "taskpane.html",
       template: "./src/taskpane/taskpane.html",
       chunks: ["polyfill", "taskpane", "commands", "functions"]
     })
   

6. Enregistrez vos changements et reconstruisez le projet.

   npm run build
   

Tester les modifications apportées à votre complément Office

Vous pouvez vérifier que vous utilisez correctement le runtime partagé en suivant les instructions suivantes.

1. Ouvrez le fichier taskpane.js.

2. Remplacez tout le contenu du fichier par le code suivant. Le nombre de fois où le volet Office a été ouvert s’affiche. L’ajout de l’événement onVisibilityModeChanged est pris en charge uniquement dans un runtime partagé.

   /*global document, Office*/
   
   let _count = 0;
   
   Office.onReady(() => {
     document.getElementById("sideload-msg").style.display = "none";
     document.getElementById("app-body").style.display = "flex";
   
     updateCount(); // Update count on first open.
     Office.addin.onVisibilityModeChanged(function (args) {
       if (args.visibilityMode === "Taskpane") {
         updateCount(); // Update count on subsequent opens.
       }
     });
   });
   
   function updateCount() {
     _count++;
     document.getElementById("run").textContent = "Task pane opened " + _count + " times.";
   }
   

3. Enregistrez vos changements et exécutez le projet.

   npm start
   

Chaque fois que vous ouvrez le volet Office, le nombre de fois où il a été ouvert est incrémenté. La valeur de _count ne sera pas perdue, car le runtime partagé maintient votre code en cours d’exécution même lorsque le volet Office est fermé.

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

Durée de vie de l’exécution

Lorsque vous ajoutez l’élément <Runtime> , vous spécifiez également une durée de long vie avec la valeur ou short. Configurez cette valeur sur long pour tirer parti de fonctionnalités telles que le démarrage de votre complément lorsque le document s’ouvre, continuer à exécuter un code après la fermeture du volet des tâches, ou utiliser CORS et DOM à partir de fonctions personnalisées.

<Runtimes>
  <Runtime resid="Taskpane.Url" lifetime="long" />
</Runtimes>

À propos du runtime partagé

Sur Windows ou sur Mac, votre complément exécute le code des boutons du ruban, des fonctions personnalisées et du volet Office dans des environnements d’exécution distincts. Cela permet de créer des limitations, telles que l'impossibilité de partager aisément des données globales ou de pouvoir accéder à l'ensemble des fonctionnalités CORS à partir d’une fonction personnalisée.

Toutefois, vous pouvez configurer votre complément Office pour partager du code dans le même runtime (également appelé runtime partagé). Vous pouvez ainsi améliorer la coordination dans votre complément et accéder au volet des tâches DOM et CORS à partir de toutes les parties de votre complément.

La configuration d’un runtime partagé permet les scénarios suivants.

• Votre complément Office peut utiliser des fonctionnalités d’interface utilisateur supplémentaires.
  • Activer et désactiver des commandes de complément
  • Exécuter un cote dans votre complément Office lors de l’ouverture du document
  • Afficher ou masquer le volet des tâches de votre complément Office
• Les éléments suivants sont disponibles uniquement pour les compléments Excel.
  • Ajouter des raccourcis clavier personnalisés à vos compléments Office
  • Créer des onglets contextuels personnalisés dans les compléments Office
  • Les fonctions personnalisées bénéficieront d'une prise en charge complète de CORS.
  • Les fonctions personnalisées peuvent appeler les API Office.js pour lire les données d’un document feuille de calcul.

Pour Office sur Windows, le runtime partagé utilise WebView2 (Basé sur Microsoft Edge Chromium) si les conditions d’utilisation sont remplies, comme expliqué dans Navigateurs et contrôles d’affichage web utilisés par les compléments Office. Sinon, il utilise Trident (Internet Explorer 11). De plus, tous les boutons affichés par votre complément sur le ruban s’exécutent dans le même runtime partagé. L’image suivante montre comment les fonctions personnalisées, l’interface utilisateur du ruban et le code du volet Office s’exécutent tous dans le même runtime.

Multiples volets des tâches

Ne concevez pas votre complément pour utiliser plusieurs volets des tâches si vous envisagez d’utiliser un runtime partagé. Un runtime partagé prend uniquement en charge l’utilisation d’un volet des tâches. Notez que tout volet des tâches sans <TaskpaneID> est considéré comme un volet des tâches différent.

Voir aussi

• Appeler des API Excel à partir d'une fonction personnalisée
• Ajouter des raccourcis clavier personnalisés à vos compléments Office
• Créer des onglets contextuels personnalisés dans les compléments Office
• Activer et désactiver des commandes de complément
• Exécuter un cote dans votre complément Office lors de l’ouverture du document
• Afficher ou masquer le volet des tâches de votre complément Office
• Tutoriel : Partager des données et des événements entre des fonctions personnalisées Excel et le volet Office
• Temps d'exécution dans les compléments Office