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

Sur les plateformes de bureau, par défaut, 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 crée des limitations, telles que le fait de ne pas pouvoir partager facilement des données globales et de ne pas pouvoir accéder à toutes les 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 (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.

Remarque

Le runtime dans lequel la boîte de dialogue Office s’exécute ne peut pas être partagé, mais ce n’est pas une limitation significative. Tenez compte des points suivants.

  • Utilisez les fonctions messageParent et messageChild pour communiquer instantanément entre un runtime de dialogue et un runtime partagé. Cela crée pour l’utilisateur une expérience identique à celle qui serait si la boîte de dialogue s’exécute dans le même runtime.
  • La fonction qui ouvre la boîte de dialogue Office peut être transmise à un paramètre qui oblige la boîte de dialogue à utiliser le même runtime qu’un volet Office parent, mais uniquement lorsque le complément s’exécute dans Office sur le Web.

Pour plus d’informations, voir Utiliser l’API de boîte de dialogue Office dans les compléments Office.

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

Cet article décrit le processus de configuration d’un complément pour utiliser un runtime partagé.

Conseil

Si le complément a été créé avec l’option pour une fonction personnalisée Excel dans microsoft 365 Agents Toolkit ou le générateur Yeoman pour les compléments Office, il est déjà configuré pour utiliser un runtime partagé.

Création du projet de complément

Pour savoir comment convertir un complément pour utiliser un runtime partagé, commencez par créer un projet de complément qui n’est pas déjà configuré pour utiliser un runtime partagé à utiliser comme exemple continu. Utilisez le Kit de ressources Agents pour créer un projet de volet office , et non un projet de fonction personnalisée. Les instructions sont fournies dans Créer des projets de complément Office avec microsoft 365 Agents Toolkit.

Remarque

Cet article utilise des noms de fichiers qui figurent dans l’exemple en cours et qui sont courants dans les compléments Office ; taskpane, commandes et fonctions. Si vous configurez un complément existant qui utilise des noms de fichiers différents, traitez ces noms de fichiers comme des espaces réservés.

Configurer le manifeste

Suivez ces étapes pour configurer un projet afin d’utiliser un runtime partagé. L’exemple de projet en cours utilise le manifeste unifié.

Importante

Si vous convertissez un complément existant qui utilise le manifeste du complément uniquement, ouvrez cet onglet. Toutefois, nous vous recommandons de commencer par convertir votre complément pour utiliser le manifeste unifié, puis de le configurer pour qu’il dispose d’un runtime partagé.

  1. Ouvrez votre projet de complément dans Visual Studio Code.

  2. Ouvrez le fichier \appPackage\manifest.json .

  3. Remplacez le "extensions.runtimes" tableau par le code JSON suivant. Notez les points suivants concernant ce balisage.

    • L’ensemble de conditions requises SharedRuntime 1.1 est spécifié dans l’objet "requirements.capabilities" . Cela configure votre complément pour qu’il s’exécute dans un runtime partagé sur les clients pris en charge. Pour obtenir la liste des clients qui prennent en charge l’ensemble de conditions requises SharedRuntime 1.1, consultez Ensembles de conditions requises du runtime partagé.

    • Le "id" du runtime est défini sur le nom "SharedRuntime"descriptif .

    • La "lifetime" propriété est définie sur "long". Il s’agit du paramètre qui permet au complément d’utiliser un runtime partagé. La valeur par défaut de "lifetime" est "short".

      Remarque

      Si vous configurez un complément existant pour utiliser un runtime partagé et qu’il a plusieurs objets dans le "runtimes" tableau, un seul objet runtime peut avoir sa "lifetime" propriété définie sur "long".

    "runtimes": [
  {
    "requirements": {
        "capabilities": [
            { 
                "name": "AddinCommands", 
                "minVersion": "1.1" 
            },
            {
                "name": "SharedRuntime",
                "minVersion": "1.1"
            }
        ]
    },
    "id": "SharedRuntime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/taskpane.html"
    },
    "lifetime": "long",
    "actions": [
      {
        "id": "TaskPaneRuntimeShow",
        "type": "openPage"
      },
      {
        "id": "action",
        "type": "executeFunction"
      }
    ]
  }
]

  4. Enregistrez vos modifications.

Configurer le fichier webpack.config.js

Dans l’exemple suivant, et probablement dans un complément existant, le webpack.config.js génère plusieurs chargeurs d’exécution. Vous devez le modifier pour charger uniquement le runtime partagé via le fichier taskpane.html .

  1. Ouvrez le fichier webpack.config.js.

  2. 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"]
  })

  3. Si vous configurez un complément fonctions personnalisées existant pour utiliser un runtime partagé, le fichier webpack.config.js contient le code de plug-in functions.html suivant, supprimez-le.

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

  4. Si votre projet a utilisé les blocs de fonctions ou de commandes , ajoutez-les à la liste des blocs du volet Office, comme indiqué dans le code suivant.

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

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

Vérifiez que vous utilisez correctement le runtime partagé en procédant comme suit.

  1. Ouvrez le fichier taskpane.js.

  2. Commentez le code existant dans le fichier, puis ajoutez le code suivant. Ce code affiche le nombre de fois où le volet Office a été ouvert. 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((args) => {
    if (args.visibilityMode === Office.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 n’est pas perdue, car le runtime partagé maintient votre code en cours d’exécution même lorsque le volet Office est fermé.

Une fois les tests terminés, suivez les meilleures pratiques pour arrêter le serveur de développement et désinstaller le complément, comme décrit dans Utiliser la fonctionnalité de désinstallation de votre outil. Restaurez ensuite le code d’origine de taskpane.js.

Bonne pratique : éviter plusieurs volets office

Un runtime partagé ne prend en charge qu’un seul volet Office, bien que ce volet office puisse avoir plusieurs pages. L’implémentation de cette pratique dépend du type de manifeste.

  • Manifeste unifié pour Microsoft 365 : Dans l’objet runtime configuré avec une "long" durée de vie, aucun des objets du "actions" tableau ne doit avoir de "view" propriété.
  • Manifeste de complément uniquement : dans l’élément ancêtre <Host> qui a un élément descendant <Runtime> défini sur une long durée de vie, aucun des éléments descendants <Action> ne doit avoir d’élément <TaskpaneID> enfant.

Voir aussi

  • Last updated on