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

  • Article

Importante

Le runtime partagé n’est pris en charge que dans certaines applications Office. Pour plus d’informations, consultez Ensembles de conditions requises pour le 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

Importante

La valeur de l’argument --name doit être entre guillemets doubles, même si elle n’a pas d’espace.

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

Remarque

Si votre projet a le fichier functions.html ou le fichier commands.html, vous pouvez les supprimer. Le taskpane.html charge le codefunctions.js et commands.js dans le runtime partagé via les mises à jour webpack que vous venez d’effectuer.

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

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.

Remarque

La valeur de la durée de vie par défaut est short, mais nous vous recommandons d’utiliser long dans les compléments Excel, PowerPoint et Word. Si vous avez défini votre runtime sur short dans cet exemple, votre complément démarre lorsque vous appuyez sur l’un de vos boutons du ruban, mais il se peut qu’il se ferme une fois l’exécution de votre gestionnaire de ruban terminée. De la même façon, le complément démarre lorsque le volet des tâches est ouvert, mais il se peut se fermer à la fermeture du volet des tâches.

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

Remarque

Si votre complément inclut l’élément <Runtimes> dans le manifeste (requis pour un runtime partagé) et que les conditions d’utilisation de WebView2 (Microsoft Edge Chromium) sont remplies, il utilise ce contrôle. Si les conditions ne sont pas remplies, il utilise le contrôle web Trident (Internet Explorer 11) indépendamment de la version Windows ou Microsoft 365. Pour plus d’informations, voir Runtimes et navigateurs et contrôles d’affichage web utilisés par les compléments Office.

À propos du runtime partagé

Sur Windows ou 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.

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.

Diagramme d’une fonction personnalisée, du volet des tâches et des boutons du ruban qui s’exécutent tous dans un runtime de navigateur partagé dans Excel.

Débogage

Lors de l’utilisation d’un runtime partagé, vous ne pouvez pas utiliser Visual Studio Code pour déboguer des fonctions personnalisées dans Excel sur Windows à cette date. Vous devez utiliser les outils de développement à la place. Pour plus d’informations, voir Déboguer des compléments à l’aide des Outils de développement pour Internet Explorer ou Déboguer des compléments à l’aide des Outils de développement dans Microsoft Edge (basés sur Chromium).

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