Edit

OneNote JavaScript API programming overview

  • Article

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.

Note

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 Commercial marketplace certification 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 1120.3 and the Office Add-in application and availability page).

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.

  • An XML 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 same manifest format as other Office Add-ins.

Office Add-in = Manifest + Webpage

Office Add-in consists of a manifest and 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.

API Notes
Office.context.document.getSelectedDataAsync Office.CoercionType.Text and Office.CoercionType.Matrix only
Office.context.document.setSelectedDataAsync Office.CoercionType.Text, Office.CoercionType.Image, and Office.CoercionType.Html only
const mySetting = Office.context.document.settings.get(name); Settings are supported by content add-ins only
Office.context.document.settings.set(name, value); Settings are supported by content add-ins only
Office.EventType.DocumentSelectionChanged None.

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.

OneNote object model diagram.

See also