OneNote JavaScript API 编程概述OneNote JavaScript API programming overview

OneNote 引入了适用于 OneNote 网页版加载项的 JavaScript API。OneNote introduces a JavaScript API for OneNote add-ins on the web. 可以创建任务窗格加载项、内容加载项,以及与 OneNote 对象交互并连接到 Web 服务或其他基于 Web 的资源的加载项命令。OneNote introduces a JavaScript API for OneNote Online add-ins. 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.

备注

如果计划将加载项发布到 AppSource 并适用于 Office 体验,请务必遵循 AppSource 验证策略。例如,加载项必须适用于支持已定义方法的所有平台,才能通过验证(有关详细信息,请参阅第 4.12 部分以及 Office 加载项主机和可用性页面)。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).

Office 加载项的组件Components of an Office Add-in

加载项由两个基本部分组成:Add-ins consist of two basic components:

  • 包含网页和所有相应 JavaScript、CSS 或其他文件的 Web 应用程序A web application consisting of a webpage and any required JavaScript, CSS, or other files. 这些文件托管在 Web 服务器或 Web 托管服务上,例如 Microsoft Azure。These files are hosted on a web server or web hosting service, such as Microsoft Azure. 在 OneNote 网页版中,Web 应用程序在浏览器控件或 iframe 中显示。In OneNote Online, the web application displays in a browser control or iframe.

  • XML 清单指定外接程序网页的 URL 和适用于外接程序的任何访问要求、设置和功能。此文件存储在客户端上。OneNote 外接程序使用与其他 Office 外接程序相同的 清单格式。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 加载项 = 清单 + 网页Office Add-in = Manifest + Webpage

Office 加载项包含清单和网页

使用 JavaScript APIUsing the JavaScript API

加载项使用托管应用程序的运行时上下文以访问 JavaScript API。API 有两层:Add-ins use the runtime context of the host application to access the JavaScript API. The API has two layers:

  • 用于执行 OneNote 专属操作的主机特定 API,可通过 Application 对象访问。A host-specific API for OneNote-specific operations, accessed through the Application object.
  • 跨 Office 应用程序分享的通用 API,通过Document 对象访问。A Common API that's shared across Office applications, accessed through the Document object.

通过 Application 对象访问主机特定 API。Accessing the host-specific API through the Application object

Application 对象可用于访问 OneNote 对象,如 NotebookSectionPageUse the Application object to access OneNote objects such as Notebook, Section, and Page. 通过主机特定 API,可在代理对象上运行批处理操作。With host-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. 创建您想要使用的表示 OneNote 对象的代理。通过读取和写入代理对象的属性和调用其方法,您可以与其同步交互。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. 调用代理上的 load 以使用在参数中指定的属性值填充它。此调用将添加至命令队列中。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.

    备注

    API 方法调用(如 context.application.getActiveSection().pages;)也会添加到队列中。Method calls to the API (such as context.application.getActiveSection().pages;) are also added to the queue.

  4. 调用 context.sync 以按它们已排队的顺序运行所有排队的命令。这将同步您正在运行的脚本和真实对象之间的状态,并通过检索已加载的用于您的脚本的 OneNote 对象的属性实现。您可以使用返回的 promise 对象以链接其他操作。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:

function getPagesInSection() {
    OneNote.run(function (context) {

        // Get the pages in the current section.
        var 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.
        return context.sync()
            .then(function () {

                // Read the id and title of each page.
                $.each(pages.items, function(index, page) {
                    var pageId = page.id;
                    var pageTitle = page.title;
                    console.log(pageTitle + ': ' + pageId);
                });
            })
            .catch(function (error) {
                app.showNotification("Error: " + error);
                console.log("Error: " + error);
                if (error instanceof OfficeExtension.Error) {
                    console.log("Debug info: " + JSON.stringify(error.debugInfo));
                }
            });
    });
}

可以在 API 参考 中找到受支持的 OneNote 对象和操作。You can find supported OneNote objects and operations in the API reference.

OneNote JavaScript API 要求集OneNote JavaScript API requirement sets

要求集是指各组已命名的 API 成员。Requirement sets are named groups of API members. Office 外接程序使用清单中指定的要求集或执行运行时检查,以确定 Office 主机是否支持外接程序所需的 API。Office Add-ins use requirement sets specified in the manifest or use a runtime check to determine whether an Office host supports APIs that an add-in needs. 有关 OneNote JavaScript API 要求集的详细信息,请参阅 OneNote JavaScript API 要求集For detailed information about OneNote JavaScript API requirement sets, see the OneNote JavaScript API requirement sets article.

通过 Document 对象访问通用 APIAccessing the Common API through the Document object

使用 Document 对象以访问通用 API,例如 getSelectedDataAsyncsetSelectedDataAsync 方法。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) {
            var error = asyncResult.error;
            if (asyncResult.status === Office.AsyncResultStatus.Failed) {
                console.log(error.message);
            }
            else $('#input').val(asyncResult.value);
        });
}

OneNote 加载项仅支持以下通用 API:OneNote add-ins support only the following Common APIs:

APIAPI 注释Notes
Office.context.document.getSelectedDataAsyncOffice.context.document.getSelectedDataAsync 仅限 Office.CoercionType.TextOffice.CoercionType.MatrixOffice.CoercionType.Text and Office.CoercionType.Matrix only
Office.context.document.setSelectedDataAsyncOffice.context.document.setSelectedDataAsync 仅限 Office.CoercionType.TextOffice.CoercionType.ImageOffice.CoercionType.HtmlOffice.CoercionType.Text, Office.CoercionType.Image, and Office.CoercionType.Html only
var mySetting = Office.context.document.settings.get(name);var mySetting = Office.context.document.settings.get(name); 设置仅受内容外接程序支持Settings are supported by content add-ins only
Office.context.document.settings.set(name, value);Office.context.document.settings.set(name, value); 设置仅受内容外接程序支持Settings are supported by content add-ins only
Office.EventType.DocumentSelectionChangedOffice.EventType.DocumentSelectionChanged

一般情况下,仅使用通用 API 执行主机特定 API 不支持的操作。In general, you only use the Common API to do something that isn't supported in the host-specific API. 若要详细了解如何使用通用 API,请参阅 Office 加载项文档参考To learn more about using the Common API, see the Office Add-ins documentation and reference.

OneNote 对象模型图OneNote object model diagram

下图表示了 OneNote JavaScript API 中当前可用的内容。The following diagram represents what's currently available in the OneNote JavaScript API.

OneNote 对象模型图

另请参阅See also