Vue d’ensemble de la programmation de l’API JavaScript de OneNote

Article
07/22/2024

OneNote présente une API JavaScript pour les compléments OneNote sur le web. Vous pouvez créer des compléments de volet Office et de contenu, ainsi que des commandes de complément qui interagissent avec les objets OneNote et se connectent à des services web ou à d’autres ressources basées sur le web.

Remarque

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 politiques de certification du marché commercial. Par exemple, pour réussir la validation, votre complément doit fonctionner sur toutes les plateformes qui prennent en charge les méthodes que vous définissez (pour en savoir plus, consultez la section 1120.3 et la page relative à la disponibilité et à l’application des compléments Office).

Composants d’un complément Office

Les compléments sont constitués de deux composants de base :

Une application web comportant une page web et les fichiers CSS, JavaScript ou autres requis. Ces fichiers sont hébergés sur un serveur web ou un service d’hébergement web, tel que Microsoft Azure. Dans OneNote sur le web, l’application web s’affiche dans un contrôle webview ou un iframe.
Manifeste qui spécifie l’URL de la page web du complément et les exigences d’accès, paramètres et fonctionnalités du complément. Ce fichier est stocké sur le client. Les compléments OneNote utilisent le format de manifeste du complément uniquement .

Complément pour Office = manifeste + page web

Le complément Office se compose d’un manifeste et d’une page web.

Utilisation de l’API JavaScript

Les compléments utilisent le contexte d’exécution de l’application Office pour accéder à l’API JavaScript. L’API comporte deux couches :

Une API spécifique à l’application pour les opérations spécifiques de OneNote, accessible via l’objetApplicationApplication.
UneAPI commune qui est partagée entre les applications Office, accessible via l’objet Document.

Accès à l’API spécifique à l’application via l’objetApplication

Utilisez l’objetApplication pour accéder aux objets OneNote tels que Notebook, Section et Page. Grâce à l’API spécifique à l’application, vous pouvez exécuter des opérations par lot sur les objets proxy. Le flux de base ressemble à ceci:

Obtenir l’instance de l’application à partir du contexte.
Créer un proxy qui représente l’objet OneNote que vous souhaitez utiliser. Vous interagissez simultanément avec les objets proxy en lisant et en écrivant leurs propriétés et en appelant leurs méthodes.
Appelez load sur le proxy pour le remplir avec les valeurs de propriété spécifiées dans le paramètre . Cet appel est ajouté à la file d’attente des commandes.

Remarque

Les appels de méthode à l’API (tels que context.application.getActiveSection().pages;) sont également ajoutés à la file d’attente.
Appelez context.sync pour exécuter toutes les commandes en file d’attente dans l’ordre dans lequel elles ont été mises en file d’attente. Cela permet de synchroniser l’état entre votre script d’exécution et les objets réels, en récupérant les propriétés des objets OneNote chargés à utiliser dans vos scripts. Vous pouvez utiliser l’objet Promise renvoyé pour créer une chaîne avec les actions supplémentaires.

Par exemple :

async function getPagesInSection() {
    await OneNote.run(async (context) => {

        // Get the pages in the current section.
        const pages = context.application.getActiveSection().pages;

        // Queue a command to load the id and title for each page.
        pages.load('id,title');

        // Run the queued commands, and return a promise to indicate task completion.
        await context.sync();
            
        // Read the id and title of each page.
        $.each(pages.items, function(index, page) {
            let pageId = page.id;
            let pageTitle = page.title;
            console.log(pageTitle + ': ' + pageId);
        });
    });
}

Pour en savoir plus sur le modèle load/sync et d’autres pratiques courantes dans les API JavaScript OneNote, consultez l’utilisation du modèle API spécifique à l’application.

Vous pouvez déterminer les objets et les opérations OneNote pris en charge dans la référence de l’API.

Ensembles de conditions requises de l’API JavaScript pour OneNote

Les ensembles de conditions requises sont des groupes nommés de membres d’API. Les compléments Office utilisent les ensembles de conditions requises spécifiés dans le manifeste ou utilisent une vérification de l’exécution pour déterminer si une application Office prend en charge les API requises par le complément. Pour en savoir plus sur les ensembles de conditions requises de l’API JavaScript pour OneNote, consultez Ensembles de conditions requises de l’API JavaScript pour OneNote.

Accès à l’API commune via l’objetDocument

Utilisez l’objet Document pour accéder à l’API commune, par exemple les méthodesgetSelectedDataAsync et setSelectedDataAsync.

Par exemple :

function getSelectionFromPage() {
    Office.context.document.getSelectedDataAsync(
        Office.CoercionType.Text,
        { valueFormat: "unformatted" },
        function (asyncResult) {
            const error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(error.message);
            }
            else $('#input').val(asyncResult.value);
        });
}

Les compléments OneNote prennent en charge uniquement les API communes suivantes.

API	Commentaires
Office.context.document.getSelectedDataAsync	Office.CoercionType.Text`Office.CoercionType.Text` et Office.CoercionType.Matrix`Office.CoercionType.Matrix` uniquement
Office.context.document.setSelectedDataAsync	`Office.CoercionType.Text`, `Office.CoercionType.Image`et `Office.CoercionType.Html` uniquement
var mySetting = Office.context.document.settings.get(name);	Les paramètres sont pris en charge par les compléments de contenu uniquement
Office.context.document.settings.set(name, value);	Les paramètres sont pris en charge par les compléments de contenu uniquement
Office.EventType.DocumentSelectionChanged	Aucune

En règle générale, vous utilisez l’API commune pour effectuer une action qui n’est pas prise en charge dans l’API spécifique à l’application. Pour plus d’informations sur les API communes, voir le Modèle d’objet API JavaScript communes.

Diagramme du modèle objet OneNote

Le diagramme suivant représente ce qui est actuellement disponible dans l’API JavaScript de OneNote.

Diagramme du modèle objet OneNote.

Partager via