OneNote JavaScript API programming overview

OneNote introduces a JavaScript API for OneNote add-ins on the web. You can create task pane add-ins, content add-ins, and add-in commands that interact with OneNote objects and connect to web services or other web-based resources.

Components of an Office Add-in

Add-ins consist of two basic components:

• A web application consisting of a webpage and any required JavaScript, CSS, or other files. These files are hosted on a web server or web hosting service, such as Microsoft Azure. In OneNote on the web, the web application displays in a webview control or iframe.

• A manifest that specifies the URL of the add-in's webpage and any access requirements, settings, and capabilities for the add-in. This file is stored on the client. OneNote add-ins use the add-in only manifest format.

Office Add-in = Manifest + Webpage

Using the JavaScript API

Add-ins use the runtime context of the Office application to access the JavaScript API. The API has two layers:

• A application-specific API for OneNote-specific operations, accessed through the Application object.
• A Common API that's shared across Office applications, accessed through the Document object.

Accessing the application-specific API through the Application object

Use the Application object to access OneNote objects such as Notebook, Section, and Page. With application-specific APIs, you run batch operations on proxy objects. The basic flow goes something like this:

1. Get the application instance from the context.

2. Create a proxy that represents the OneNote object you want to work with. You interact synchronously with proxy objects by reading and writing their properties and calling their methods.

3. Call load on the proxy to fill it with the property values specified in the parameter. This call is added to the queue of commands.

   Note

   Method calls to the API (such as context.application.getActiveSection().pages;) are also added to the queue.

4. Call context.sync to run all queued commands in the order that they were queued. This synchronizes the state between your running script and the real objects, and by retrieving properties of loaded OneNote objects for use in your script. You can use the returned promise object for chaining additional actions.

For example:

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);
        });
    });
}

See Using the application-specific API model to learn more about the load/sync pattern and other common practices in the OneNote JavaScript APIs.

You can find supported OneNote objects and operations in the API reference.

OneNote JavaScript API requirement sets

Requirement sets are named groups of API members. Office Add-ins use requirement sets specified in the manifest or use a runtime check to determine whether an Office application supports APIs that an add-in needs. For detailed information about OneNote JavaScript API requirement sets, see OneNote JavaScript API requirement sets.

Accessing the Common API through the Document object

Use the Document object to access the Common API, such as the getSelectedDataAsync and setSelectedDataAsync methods.

For example:

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);
        });
}

OneNote add-ins support only the following Common APIs.

In general, you use the Common API to do something that isn't supported in the application-specific API. To learn more about using the Common API, see Common JavaScript API object model.

OneNote object model diagram

The following diagram represents what's currently available in the OneNote JavaScript API.

See also

• Developing Office Add-ins
• Build your first OneNote add-in
• OneNote JavaScript API reference
• Sample: Rubric Grader