Temps d'exécution dans les compléments Office

  • Article

Les compléments Office s’exécutent dans des runtimes incorporés dans Office. En tant que langage interprété, JavaScript doit s’exécuter dans un runtime JavaScript. Node.js et les navigateurs modernes sont des exemples de ces runtimes.

Types de runtimes

Il existe deux types de runtimes utilisés par les compléments Office :

Vous trouverez plus d’informations sur ces types plus loin dans cet article dans Runtime JavaScript uniquement et Runtime du navigateur.

Le tableau suivant indique les fonctionnalités possibles d’un complément qui utilisent chaque type de runtime.

Type de runtime Fonctionnalité de complément
JavaScript uniquement Fonctions
personnalisées Excel (sauf lorsque le runtime est partagé ou que le complément s’exécute dans Office sur le Web)

Tâche
basée sur les événements Outlook (uniquement lorsque le complément est en cours d’exécution dans Outlook sur Windows)

Fonctionnalité de création de rapports de courrier indésirable intégré Outlook (préversion)
(uniquement lorsque le complément s’exécute dans Outlook sur Windows)
Navigateur volet

officeDialogue

function, commande

Fonctions personnalisées
Excel(lorsque le runtime est partagé ou que le complément est en cours d’exécution dans Office sur le Web)

Tâche
basée sur les événements Outlook (lorsque le complément s’exécute dans Outlook sur Mac ou Outlook sur le web)

Fonctionnalité de création de rapports de courrier indésirable intégré Outlook (préversion)
(uniquement lorsque le complément s’exécute dans Outlook sur Mac ou sur le web ou dans le nouvel Outlook sur Windows (préversion))

Le tableau suivant présente les mêmes informations organisées selon le type de runtime utilisé pour les différentes fonctionnalités possibles d’un complément.

Fonctionnalité de complément Type de runtime sur Windows Type de runtime sur Mac Type de runtime sur le web
Fonctions personnalisées dans Excel JavaScript uniquement
(mais navigateur lorsque le runtime est partagé)		 JavaScript uniquement
(mais navigateur lorsque le runtime est partagé)		 Navigateur
Tâches basées sur les événements Outlook JavaScript uniquement
(Outlook classique sur Windows)

browser
(nouveau Outlook sur Windows (préversion))		 Navigateur Navigateur
Fonctionnalité intégrée de création de rapports de courrier indésirable d’Outlook (préversion) JavaScript uniquement
(Outlook classique sur Windows)

browser
(nouveau Outlook sur Windows (préversion))		 Navigateur Navigateur
volet Office Navigateur Navigateur Navigateur
fenêtre de dialogue Navigateur Navigateur Navigateur
function, commande Navigateur Navigateur Navigateur

Dans Office sur le Web, tout s’exécute toujours dans un runtime de type navigateur. À une exception près, tout ce qui se trouve dans un complément sur le web s’exécute dans le même processus de navigateur : le processus de navigateur dans lequel l’utilisateur a ouvert Office sur le Web. L’exception est lorsqu’une boîte de dialogue est ouverte avec un appel d’Office.ui.displayDialogAsync et que l’option DialogOptions.displayInIFramen’est pas passée et définie sur true. Lorsque l’option n’est pas passée (elle a donc la valeur par défaut false ), la boîte de dialogue s’ouvre dans son propre processus. Le même principe s’applique à la méthode OfficeRuntime.displayWebDialog et à l’option OfficeRuntime.DisplayWebDialogOptions.displayInIFrame .

Lorsqu’un complément s’exécute sur une plateforme autre que le web, les principes suivants s’appliquent.

  • Un dialogue s’exécute dans son propre processus d’exécution.

  • Un complément outlook basé sur les événements ou la création de rapports de courrier indésirable s’exécute dans son propre processus d’exécution.

    Remarque

    Les fonctionnalités d’activation basée sur les événements et de création de rapports de courrier indésirable intégrées dans Outlook doivent utiliser le même runtime. Les runtimes multiples ne sont actuellement pas pris en charge dans Outlook.

  • Par défaut, les volets Office, les commandes de fonction et les fonctions personnalisées Excel s’exécutent dans leur propre processus d’exécution. Toutefois, pour certaines applications hôtes Office, le manifeste de complément peut être configuré pour que les deux ou les trois puissent s’exécuter dans le même runtime. Consultez Runtime partagé.

Selon l’application Office hôte et les fonctionnalités utilisées dans le complément, il peut y avoir de nombreux runtimes dans un complément. Chaque s’exécute généralement dans son propre processus, mais pas nécessairement simultanément. Les éléments suivants sont des exemples.

  • Un complément PowerPoint ou Word qui ne partage aucun runtime et inclut les fonctionnalités suivantes, a jusqu’à trois runtimes.

    • Un volet Office

    • Commande de fonction

    • Boîte de dialogue (Une boîte de dialogue peut être lancée à partir du volet Office ou de la commande de fonction.)

      Remarque

      Il n’est pas recommandé d’ouvrir simultanément plusieurs boîtes de dialogue, mais si le complément permet à l’utilisateur d’en ouvrir une à partir du volet Office et une autre à partir de la commande de fonction en même temps, ce complément aura quatre runtimes. Un volet Office et un appel donné d’une commande de fonction ne peuvent avoir qu’une seule boîte de dialogue ouverte à la fois ; mais si la commande de fonction est appelée plusieurs fois, un nouveau dialogue est ouvert par-dessus son prédécesseur à chaque appel, de sorte qu’il peut y avoir de nombreux runtimes. Le reste de cette liste ignore la possibilité de plusieurs dialogues ouverts.

  • Un complément Excel qui ne partage aucun runtime et inclut les fonctionnalités suivantes comporte jusqu’à quatre runtimes.

    • Un volet Office
    • Commande de fonction
    • Une fonction personnalisée
    • Une boîte de dialogue (Une boîte de dialogue peut être lancée à partir du volet Office, de la commande de fonction ou d’une fonction personnalisée.)

  • Un complément Excel avec les mêmes fonctionnalités et est configuré pour partager le même runtime dans le volet Office, la commande de fonction et la fonction personnalisée a deux runtimes. Un runtime partagé ne peut ouvrir qu’un seul dialogue à la fois.

  • Un complément Excel avec les mêmes fonctionnalités, sauf qu’il n’a pas de boîte de dialogue et qu’il est configuré pour partager le même runtime dans le volet Office, la commande de fonction et la fonction personnalisée, a un runtime.

  • Un complément Outlook doté des fonctionnalités suivantes comporte jusqu’à quatre runtimes. Les runtimes partagés ne sont pas pris en charge dans Outlook.

    • Un volet Office
    • Commande de fonction
    • Une tâche basée sur les événements ou une fonctionnalité intégrée de création de rapports de courrier indésirable
    • Boîte de dialogue (Une boîte de dialogue peut être lancée à partir du volet Office ou de la commande de fonction, mais pas à partir d’une tâche basée sur les événements.)

Partager des données entre les runtimes

Remarque

  • Si vous savez que votre complément sera utilisé uniquement dans Office sur le Web et qu’il n’ouvrira aucune boîte de dialogue avec l’option displayInIFrame définie sur true, vous pouvez ignorer cette section. Étant donné que tous les éléments de votre complément s’exécutent dans le même processus d’exécution, vous pouvez simplement utiliser des variables globales pour partager des données entre les fonctionnalités.
  • Comme indiqué ci-dessus dans Types de runtimes, le type de runtime utilisé par une fonctionnalité varie en partie selon la plateforme. Il est recommandé d’éviter d’avoir du code de complément qui se branche en fonction de la plateforme. Par conséquent, les conseils de cette section recommandent des techniques qui fonctionnent sur plusieurs plateformes. Il n’existe qu’un seul cas, indiqué ci-dessous, dans lequel le code de branchement est requis.

Pour les compléments Excel, PowerPoint et Word, utilisez un runtime partagé lorsque deux fonctionnalités ou plus, à l’exception des boîtes de dialogue, doivent partager des données. Dans Outlook, ou dans les scénarios où le partage d’un runtime n’est pas possible, vous avez besoin d’autres méthodes. Les parties du complément qui se trouvent dans des processus d’exécution distincts ne partagent pas automatiquement les données globales et sont traitées par le serveur d’applications web du complément comme des sessions distinctes, de sorte que Window.sessionStorage ne peut pas être utilisé pour partager des données entre elles. Les conseils suivants partent du principe que vous n’utilisez pas de runtime partagé.

  • Transmettez des données entre un dialogue et son volet Office parent, sa commande de fonction ou sa fonction personnalisée à l’aide des méthodes Office.ui.messageParent et Dialog.messageChild .

    Remarque

    Les OfficeRuntime.storage méthodes ne pouvant pas être appelées dans un dialogue, il ne s’agit pas d’une option de partage de données entre un dialogue et un autre runtime.

  • Pour partager des données entre un volet office et une commande de fonction, stockez les données dans Window.localStorage, qui est partagé entre tous les runtimes qui accèdent à la même origine spécifique.

    Remarque

    LocalStorage n’est pas accessible dans un runtime JavaScript uniquement et, par conséquent, il n’est pas disponible dans les fonctions personnalisées Excel. Il ne peut pas non plus être utilisé pour partager des données avec des tâches basées sur des événements Outlook (car ces tâches utilisent un runtime JavaScript uniquement sur certaines plateformes).

    À compter de la version 115 des navigateurs basés sur Chromium, tels que Chrome et Edge, le partitionnement du stockage est testé pour empêcher le suivi intersites par canal latéral spécifique (voir aussi stratégies de navigateur Microsoft Edge). Cela signifie que les données stockées par les API de stockage, telles que le stockage local, ne sont disponibles que pour les contextes ayant la même origine et le même site de niveau supérieur. Pour contourner ce problème, dans votre navigateur, accédez à chrome://flags ou edge://flags, puis définissez l’indicateur De partitionnement de stockage tiers expérimental (#third-party-storage-partitioning) sur Désactivé.

    Conseil

    Les données dans Window.localStorage sont conservées entre les sessions du complément et sont partagées par des compléments ayant la même origine. Ces deux caractéristiques sont souvent indésirables pour un complément.

    • Pour vous assurer que chaque session d’un complément donné démarre à nouveau, appelez la méthode Window.localStorage.clear au démarrage du complément.
    • Pour autoriser la persistance de certaines valeurs stockées, mais réinitialiser d’autres valeurs, utilisez Window.localStorage.setItem lorsque le complément démarre pour chaque élément qui doit être réinitialisé à une valeur initiale.
    • Pour supprimer entièrement un élément, appelez Window.localStorage.removeItem.

  • Pour partager des données entre une fonction personnalisée Excel et tout autre runtime, utilisez OfficeRuntime.storage.

  • Pour partager des données entre une tâche basée sur des événements Outlook et une commande de volet office ou de fonction, vous devez brancher votre code selon la valeur de la propriété Office.context.platform .

    • Lorsque la valeur est PC (Windows), stockez et récupérez des données à l’aide des API Office.sessionData .
    • Lorsque la valeur est Mac, utilisez Window.localStorage comme décrit précédemment dans cette liste.

Voici d’autres façons de partager des données :

  • Stockez des données partagées dans une base de données en ligne accessible à tous les runtimes.
  • Stockez les données partagées dans un cookie pour le domaine du complément afin de les partager entre les runtimes de navigateur. Les runtimes JavaScript uniquement ne prennent pas en charge les cookies.

Pour plus d’informations, voir Conserver l’état et les paramètres du complément et Obtenir et définir des métadonnées de complément pour un complément Outlook.

Runtime JavaScript uniquement

Le runtime JavaScript uniquement utilisé dans les compléments Office est une modification d’un runtime de open source créé à l’origine pour React Native. Il contient un moteur JavaScript complété par la prise en charge de WebSockets, full CORS (Cross-Origin Resource Sharing) et OfficeRuntime.storage. Il n’a pas de moteur de rendu et ne prend pas en charge les cookies ou le stockage local.

Ce type de runtime est utilisé dans les compléments basés sur les événements et la création de rapports de courrier indésirable dans Outlook sur Windows uniquement et dans les fonctions personnalisées Excel , sauf lorsque les fonctions personnalisées partagent un runtime.

  • Lorsqu’il est utilisé pour une fonction personnalisée Excel, le runtime démarre lorsque la feuille de calcul est recalculée ou que la fonction personnalisée calcule. Il ne s’arrête pas tant que le classeur n’est pas fermé.

  • Lorsqu’il est utilisé dans un complément de création de rapports de courrier indésirable ou basé sur des événements Outlook, le runtime démarre lorsque l’événement se produit. Elle se termine lorsque le premier des éléments suivants se produit.

    • Le gestionnaire d’événements appelle la completed méthode de son paramètre d’événement.
    • Cinq minutes se sont écoulées depuis l’événement de déclenchement.
    • L’utilisateur change de focus à partir de la fenêtre où l’événement a été déclenché, par exemple une fenêtre de composition de message (s’applique uniquement aux compléments basés sur les événements).

    Remarque

    Les fonctionnalités d’activation basée sur les événements et de création de rapports de courrier indésirable intégrées dans Outlook doivent utiliser le même runtime. Les runtimes multiples ne sont actuellement pas pris en charge dans Outlook.

Un runtime JavaScript uniquement utilise moins de mémoire et démarre plus rapidement qu’un runtime de navigateur, mais a moins de fonctionnalités.

Importante

Le runtime JavaScript uniquement prend directement en charge la norme ECMAScript 2016 de JavaScript, mais vous pouvez utiliser des versions ultérieures de JavaScript ou TypeScript. Pour plus d’informations sur la procédure à suivre, consultez Prise en charge des versions récentes de JavaScript.

Runtime du navigateur

Les compléments Office utilisent un runtime de type de navigateur différent en fonction de la plateforme sur laquelle Office s’exécute (web, Mac ou Windows), ainsi que de la version et de la build de Windows et d’Office. Par exemple, si l’utilisateur exécute Office sur le Web dans un navigateur FireFox, le runtime Firefox est utilisé. Si l’utilisateur exécute Office sur Mac, le runtime Safari est utilisé. Si l’utilisateur exécute Office sur Windows, un Explorer Edge ou Internet fournit le runtime, en fonction de la version de Windows et d’Office. Pour plus d’informations, consultez Navigateurs et contrôles d’affichage web utilisés par les compléments Office.

Tous ces runtimes incluent un moteur de rendu HTML et prennent en charge les WebSockets, cors full CORS (Cross-Origin Resource Sharing) et le stockage local et les cookies.

La durée de vie d’exécution d’un navigateur varie selon la fonctionnalité qu’il implémente et selon qu’elle est partagée ou non.

  • Lorsqu’un complément avec un volet Office est lancé, un runtime de navigateur démarre, sauf s’il s’agit d’un runtime partagé qui est déjà en cours d’exécution. S’il s’agit d’un runtime partagé, il s’arrête lorsque le document est fermé. S’il ne s’agit pas d’un runtime partagé, il s’arrête lorsque le volet Office est fermé.

  • Lorsqu’une boîte de dialogue est ouverte, un runtime de navigateur démarre. Il s’arrête lorsque la boîte de dialogue est fermée.

  • Lorsqu’une commande de fonction est exécutée (ce qui se produit lorsqu’un utilisateur sélectionne son bouton ou élément de menu), un runtime de navigateur démarre, sauf s’il s’agit d’un runtime partagé qui est déjà en cours d’exécution. S’il s’agit d’un runtime partagé, il s’arrête lorsque le document est fermé. S’il ne s’agit pas d’un runtime partagé, il s’arrête lorsque le premier des éléments suivants se produit.

    • La commande de fonction appelle la completed méthode de son paramètre d’événement.
    • Cinq minutes se sont écoulées depuis l’événement de déclenchement. (Si un dialogue a été ouvert dans la commande de fonction et qu’il est toujours ouvert lorsque le runtime parent expire, le runtime de dialogue reste en cours d’exécution jusqu’à ce que le dialogue soit fermé.)

  • Lorsqu’une fonction personnalisée Excel utilise un runtime partagé, un runtime de type navigateur démarre lorsque la fonction personnalisée calcule si le runtime partagé n’a pas déjà démarré pour une autre raison. Il s’arrête lorsque le document est fermé.

Remarque

Lorsqu’un runtime est partagé, votre code peut fermer le volet Office sans arrêter le complément. Pour plus d’informations, voir Afficher ou masquer le volet Office de votre complément Office .

Un runtime de navigateur a plus de fonctionnalités qu’un runtime JavaScript uniquement, mais démarre plus lentement et utilise plus de mémoire.

Runtime partagé requis

Un « runtime partagé » n’est pas un type de runtime. Il fait référence à un runtime de type navigateur qui est partagé par les fonctionnalités du complément qui, sinon, auraient chacun leur propre runtime. Plus précisément, vous avez la possibilité de configurer le volet Office et les commandes de fonction du complément pour partager un runtime. Dans un complément Excel, vous pouvez également configurer des fonctions personnalisées pour partager le runtime d’un volet Office ou d’une commande de fonction, ou les deux. Dans ce cas, les fonctions personnalisées s’exécutent dans un runtime de type navigateur, au lieu d’un runtime JavaScript uniquement , comme autrement. Consultez Configurer votre complément pour utiliser un runtime partagé pour plus d’informations sur les avantages et les limitations du partage des runtimes et pour obtenir des instructions pour configurer le complément pour utiliser un runtime partagé. En bref, le runtime JavaScript uniquement utilise moins de mémoire et démarre plus rapidement, mais a moins de fonctionnalités.

Remarque

  • Vous pouvez partager des runtimes uniquement dans Excel, PowerPoint et Word.
  • Vous ne pouvez pas configurer une boîte de dialogue pour partager un runtime. Chaque dialogue a toujours son propre, sauf lorsque le dialogue est lancé dans Office sur le Web avec l’option displayInIFrame définie sur true.
  • Un runtime partagé n’utilise jamais le runtime Microsoft Edge WebView (EdgeHTML) d’origine. Si les conditions d’utilisation de Microsoft Edge avec WebView2 (basé sur Chromium) sont remplies (comme spécifié dans Navigateurs et contrôles d’affichage web utilisés par les compléments Office), ce runtime est utilisé. Sinon, le runtime Internet Explorer 11 est utilisé.