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

L’API JavaScript OneNote vous permet de créer des compléments qui étendent OneNote sur le web. Vous pouvez créer des compléments de volet Office, des compléments de contenu et des commandes de complément qui interagissent avec des objets OneNote et se connectent à des services web ou à d’autres ressources.

Composants d’un complément Office

Les compléments Office ont deux composants principaux :

• Une application web avec une page web et tous les fichiers JavaScript, CSS 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

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 :

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

Accéder à l’API spécifique à l’application via l’objet Application

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 fonctionne comme suit :

1. Obtenir l’instance de l’application à partir du contexte.

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

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

4. 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éder à l’API commune via l’objet Document

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.

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 l’utilisation de l’API commune, consultez Modèle objet d’API JavaScript commun.

Diagramme du modèle objet OneNote

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

Voir aussi

• Développement de compléments Office
• Créer votre premier complément OneNote
• Référence de l’API JavaScript de OneNote
• Exemple : Complément du volet Office du nuanceur de rubrique pour OneNote sur le web