Présentation de l’API JavaScript pour OfficeUnderstanding the JavaScript API for Office

Cet article fournit des informations sur l’API JavaScript pour Office et son utilisation. Pour obtenir des informations de référence, voir API JavaScript pour Office. Pour plus d’informations sur la mise à jour des fichiers de projet Visual Studio vers la version la plus récente de l’API JavaScript pour Office, voir Mettre à jour la version de votre API JavaScript pour Office et les fichiers de schéma manifeste.This article provides information about the JavaScript API for Office and how to use it. For reference information, see JavaScript API for Office. For information about updating Visual Studio project files to the most current version of the JavaScript API for Office, see Update the version of your JavaScript API for Office and manifest schema files.

Notes

Si vous prévoyez de publier votre complément sur AppSource et de le rendre disponible dans l’expérience Office, assurez-vous que vous respectez les stratégies de validation AppSource. Par exemple, pour réussir la validation, votre complément doit fonctionner sur toutes les plateformes prenant en charge les méthodes définies (pour en savoir plus, consultez la section 4.12 et la page relative à la disponibilité des compléments Office sur les plateformes et les hôtes).If you plan to publish your add-in to AppSource and make it available within the Office experience, make sure that you conform to the AppSource validation policies. For example, to pass validation, your add-in must work across all platforms that support the methods that you define (for more information, see section 4.12 and the Office Add-in host and availability page).

Référencer la bibliothèque de l’interface API JavaScript pour Office dans votre complémentReferencing the JavaScript API for Office library in your add-in

La bibliothèque de l’interface API JavaScript pour Office comprend le fichier Office.js et des fichiers .js propres aux applications hôtes associées, comme Excel-15.js et Outlook15.js. La méthode la plus simple pour référencer l’interface API est d’utiliser notre CDN en ajoutant le <script> suivant à la balise <head> de votre page :The JavaScript API for Office library consists of the Office.js file and associated host application-specific .js files, such as Excel-15.js and Outlook-15.js. The simplest method of referencing the API is using our CDN by adding the following <script> to your page's <head> tag:

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/office.js" type="text/javascript"></script>

Cette opération permet de télécharger et de mettre en cache les fichiers de l’interface API JavaScript pour Office lors du premier chargement de votre complément pour garantir qu’elle utilise l’implémentation d’Office.js la plus récente et les fichiers .js qui lui sont associés pour la version indiquée.This will download and cache the JavaScript API for Office files the first time your add-in loads to make sure that it is using the most up-to-date implementation of Office.js and its associated files for the specified version.

Pour obtenir plus d’informations sur le CDN Office.js et la gestion du contrôle de version et de la rétrocompatibilité, consultez la page relative au référencement de la bibliothèque de l’interface API JavaScript pour Office à partir de son réseau de distribution de contenu (CDN).For more details around the Office.js CDN, including how versioning and backward compatibility is handled, see Referencing the JavaScript API for Office library from its content delivery network (CDN).

Initialisation de votre complémentInitializing your add-in

S’applique à : tous les types de complémentApplies to: All add-in types

Les compléments Office ont souvent une logique de démarrage pour effectuer des actions telles que :Office Add-ins often have start-up logic to do things such as:

  • Vérifiez que version de l’utilisateur d’Office prendra en charge tous les API Office que votre code appelle.Check that the user's version of Office will support all the Office APIs that your code calls.

  • Vérifiez l’existence de certains artefacts tels que des feuille de calcul avec un nom spécifique.Ensure the existence of certain artifacts, such as worksheet with a specific name.

  • Avertir l’utilisateur pour sélectionner certaines cellules dans Excel, puis insérer un graphique initialisé avec ces valeurs sélectionnées.Prompting the user to select some cells in Excel, and then inserting a chart initialized with those selected values.

  • Établir des liaisons.Establish bindings.

  • Utilisez la boîte de dialogue Office API pour inviter l’utilisateur pour les valeurs de paramètres des compléments par défaut.Use the Office dialog API to prompt the user for default add-in settings values.

Mais votre code de démarrage ne doit pas appeler une API Office.js tant que la bibliothèque n’est pas chargée.But your start-up code must not call any Office.js APIs until the library is loaded. Il existe deux manières pour votre code de s’assurer que la bibliothèque est chargée.There are two ways that your code can ensure that the library is loaded. Ceci est décrit en détail dans les sections ci-après :They are described in the following sections:

Conseil

Au lieu de Office.initialize, nous vous recommandons d’utiliser Office.onReady().We recommend that you use Office.onReady() instead of Office.initialize. Office.initialize est toujours pris en charge, mais Office.onReady() offre plus de flexibilité.Although Office.initialize is still supported, using Office.onReady() provides more flexibility. Vous ne pouvez assigner qu’un seul gestionnaire à Office.initialize et il n’est appelé qu’une seule fois par l’infrastructure d’Office, mais vous pouvez appeler Office.onReady()à plusieurs endroits dans votre code et utiliser des rappels différents.You can assign only one handler to Office.initialize and it's called only once by the Office infrastructure, but you can call Office.onReady() in different places in your code and use different callbacks.

Pour plus d’informations sur les différences entre ces techniques, reportez-vous à la rubrique Différences majeures entre Office.initialize et Office.onReady().For information about the differences in these techniques, see Major differences between Office.initialize and Office.onReady().

Pour plus de détails sur la séquence d’événements lors de l’initialisation d’un complément, reportez-vous à la rubrique Chargement du DOM et environnement d’exécution.For more details about the sequence of events when an add-in is initialized, see Loading the DOM and runtime environment.

Initialiser avec Office.onReady()Initialize with Office.onReady()

Office.onReady() est une méthode asynchrone qui renvoie un objet Promise tandis qu’il vérifie si la bibliothèque Office.js est chargée.Office.onReady() is an asynchronous method that returns a Promise object while it checks to see if the Office.js library is loaded. Uniquement lorsque la bibliothèque est chargée, cela résout la promesse sous forme d’objet qui spécifie l’application Office hôte avec uneOffice.HostType valeur enum (Excel, Word, etc.) et la plateforme avec uneOffice.PlatformType valeur enum (PC, Mac, OfficeOnline, etc..).When the library is loaded, it resolves the Promise as an object that specifies the Office host application with an Office.HostType enum value (Excel, Word, etc.) and the platform with an Office.PlatformType enum value (PC, Mac, OfficeOnline, etc.). L’objet Promise se résout immédiatement si la bibliothèque est déjà chargée quand Office.onReady() est appelée.The Promise resolves immediately if the library is already loaded when Office.onReady() is called.

Une méthode pour appeler Office.onReady() consiste à transmettre une méthode de rappel.One way to call Office.onReady() is to pass it a callback method. Voici un exemple :Here's an example:

Office.onReady(function(info) {
    if (info.host === Office.HostType.Excel) {
        // Do Excel-specific initialization (for example, make add-in task pane's
        // appearance compatible with Excel "green").
    }
    if (info.platform === Office.PlatformType.PC) {
        // Make minor layout changes in the task pane.
    }
    console.log(`Office.js is now ready in ${info.host} on ${info.platform}`);
});

Par ailleurs, vous pouvez mettre en chaîne unethen() méthode permettant d’appeler Office.onReady(), au lieu de spécifier un rappel.Alternatively, you can chain a then() method to the call of Office.onReady(), instead of passing a callback. Par exemple, le code suivant vérifie que la version de l’utilisateur d’Excel prend en charge tous les API que le complément peut appeler.For example, the following code checks to see that the user's version of Excel supports all the APIs that the add-in might call.

Office.onReady()
    .then(function() {
        if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
            console.log("Sorry, this add-in only works with newer versions of Excel.");
        }
    });

Voici le même exemple utilisant les mots clés async et await dans TypeScript :Here is the same example using the async and await keywords in TypeScript:

(async () => {
    await Office.onReady();
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
})();

Si vous utilisez des infrastructures JavaScript supplémentaires qui incluent leur propre gestionnaire d’initialisation ou tests, elles doivent êtrehabituellement placées dans la réponse àOffice.onReady().If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should usually be placed within the response to Office.onReady(). Par exemple, la fonction $(document).ready() de JQuery sera référencée comme suit :For example, JQuery's $(document).ready() function would be referenced as follows:

Office.onReady(function() {
    // Office is ready
    $(document).ready(function () {
        // The document is ready
    });
});

Toutefois, il existe des exceptions à cette pratique.However, there are exceptions to this practice. Par exemple, supposons que vous voulez ouvrir votre complément dans un navigateur (au lieu de le charger dans un hôte Office) afin de déboguer votre interface utilisateur avec les outils de navigateur.For example, suppose you want to open your add-in in a browser (instead of sideload it in an Office host) in order to debug your UI with browser tools. Étant donné que Office.js ne sera pas chargé dans le navigateur, onReady ne s’exécutera pas et le $(document).ready ne s’exécutera pas si cette opération est appelée à l’intérieur d’Office onReady.Since Office.js won't load in the browser, onReady won't run and the $(document).ready won't run if it's called inside the Office onReady. Une autre exception : vous souhaitez qu’un indicateur de progression s’affiche dans le volet Office tandis que le complément se charge.Another exception: you want a progress indicator to appear in the task pane while the add-in is loading. Dans ce scénario, votre code doit appeler la jQuery ready et utiliser le rappel pour afficher l’indicateur de progression.In this scenario, your code should call the jQuery ready and use it's callback to render the progress indicator. Puis le rappel onReady Office peut remplacer l’indicateur de progression par l’interface utilisateur final.Then the Office onReady's callback can replace the progress indicator with the final UI.

Initialiser avec Office.initializeInitialize with Office.initialize

Un événement initialisé se déclenche lorsque la bibliothèque Office.js est chargée et prête pour une interaction avec l’utilisateur.An initialize event fires when the Office.js library is loaded and ready for user interaction. Vous pouvez attribuer un gestionnaire à Office.initialize qui implémente votre logique d’initialisation.You can assign a handler to Office.initialize that implements your initialization logic. L’exemple suivant vérifie que la version de l’utilisateur d’Excel prend en charge tous les API que le complément peut appeler.The following is an example that checks to see that the user's version of Excel supports all the APIs that the add-in might call.

Office.initialize = function () {
    if (!Office.context.requirements.isSetSupported('ExcelApi', '1.7')) {
        console.log("Sorry, this add-in only works with newer versions of Excel.");
    }
};

Si vous utilisez des infrastructures JavaScript supplémentaires qui incluent leur propre gestionnaire d’initialisation ou tests, elles doivent êtrehabituellement placées dans l’événementOffice.initialize.If you are using additional JavaScript frameworks that include their own initialization handler or tests, these should usually be placed within the Office.initialize event. (Mais les exceptions décrites dans la section initialiser avec Office.onReady() précédente s’appliquent dans ce cas également.) Par exemple, la fonction JQuery $(document).ready() serait référencée comme suit :(But the exceptions described in the Initialize with Office.onReady() section earlier apply in this case also.) For example, JQuery's $(document).ready() function would be referenced as follows:

Office.initialize = function () {
    // Office is ready
    $(document).ready(function () {
        // The document is ready
    });
  };

Pour les compléments de tâches et de contenu, Office.initialize fournit un paramètre_raison_ supplémentaire.For task pane and content add-ins, Office.initialize provides an additional reason parameter. Ce paramètre peut être utilisé pour savoir comment un complément a été ajouté au document actif.This parameter specifies how an add-in was added to the current document. Vous pouvez l’utiliser pour fournir une logique différente quand un complément est inséré pour la première fois par opposition au moment où il fait déjà partie du document.You can use this to provide different logic for when an add-in is first inserted versus when it already existed within the document.

Office.initialize = function (reason) {
    $(document).ready(function () {
        switch (reason) {
            case 'inserted': console.log('The add-in was just inserted.');
            case 'documentOpened': console.log('The add-in is already part of the document.');
        }
    });
 };

Pour plus d’informations, consultez les pages relatives à l’événement Office.initialize et à l’énumération InitializationReason.For more information, see Office.initialize Event and InitializationReason Enumeration.

Principales différences entre Office.initialize et Office.onReadyMajor differences between Office.initialize and Office.onReady

  • Vous ne pouvez assigner qu’un seul gestionnaire à Office.initialize et il n’est appelé qu’une seule fois par l’infrastructure d’Office, mais vous pouvez appeler Office.onReady()à plusieurs endroits dans votre code et utiliser des rappels différents.You can assign only one handler to Office.initialize and it's called only once by the Office infrastructure; but you can call Office.onReady() in different places in your code and use different callbacks. Par exemple, votre code pourrait appeler Office.onReady() dès que votre script personnalisé charge avec un rappel qui exécute la logique d’initialisation ; et votre code peut également comporter un bouton dans le volet Office dont le script appelle Office.onReady() avec un rappel différent.For example, your code could call Office.onReady() as soon as your custom script loads with a callback that runs initialization logic; and your code could also have a button in the task pane, whose script calls Office.onReady() with a different callback. Si c’est le cas, le deuxième rappel s’exécute quand l’utilisateur clique sur le bouton.If so, the second callback runs when the button is clicked.

  • L’événementOffice.initialize se déclenche à la fin du processus interne dans lequel Office.js s’initialise lui-même.The Office.initialize event fires at the end of the internal process in which Office.js initializes itself. Et il se déclenche immédiatement après la fin du processus interne.And it fires immediately after the internal process ends. Si le code dans lequel vous attribuez un gestionnaire à l’événement s’exécute trop longtemps après le déclenchement de l’événement, votre gestionnaire ne s’exécutera pas.If the code in which you assign a handler to the event executes too long after the event fires, then your handler doesn't run. Par exemple, si vous utilisez le Gestionnaire des tâches WebPack, il peut configurer page d’accueil du complément pour charger les fichiers polyfill une fois que le serveur charge Office.js mais avant que le serveur ne charge votre code JavaScript personnalisé.For example, if you are using the WebPack task manager, it might configure the add-in's home page to load polyfill files after it loads Office.js but before it loads your custom JavaScript. Le temps que votre script se charge et affecte le Gestionnaire, l’événement initialisé s’est déjà produit.By the time your script loads and assigns the handler, the initialize event has already happened. Mais il n’est jamais « trop tard » pour appeler Office.onReady().But it is never "too late" to call Office.onReady(). Si l’événement initialisé s’est déjà produit, le rappel s’exécute immédiatement.If the initialize event has already happened, the callback runs immediately.

Notes

Même si vous n’avez aucune logique de démarrage, appelez Office.onReady() ou attribuez une fonction vide à Office.initialize lorsque votre complément JavaScript se charge.Even if you have no start-up logic, you should either call Office.onReady() or assign an empty function to Office.initialize when your add-in JavaScript loads. Certaines combinaisons de plateforme et d’hôte Office ne chargeront pas le volet Office tant que l’une de ces situations se produisent.Some Office host and platform combinations won't load the task pane until one of these happens. Les exemples suivants présentent ces deux approches.The following examples show these two approaches.

Office.onReady();
Office.initialize = function () {};

Modèle d’objet API JavaScript OfficeOffice JavaScript API object model

Une fois initialisé, le complément peut interagir avec l’hôte (par exemple, Excel, Outlook).Once initialized, the add-in can interact with the host (e.g. Excel, Outlook). La page Modèle objet API JavaScript Office comporte plus d’informations sur les modèles d’utilisation spécifiques.The Office JavaScript API object model page has more details on specific usage patterns. Il existe également une documentation de référence détaillée pour les deux APIs Communes et spécifiques.There is also detailed reference documentation for both Common APIs and host-specific APIs.