Introducción a la programación de API de JavaScript para OneNoteOneNote JavaScript API programming overview

OneNote introduce una API de JavaScript para complementos de OneNote en la web.OneNote introduces a JavaScript API for OneNote add-ins on the web. Puede crear complementos de panel de tareas, complementos de contenido y comandos de complementos que interactúan con objetos de OneNote y se conectan a servicios web o a otros recursos basados en 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.

Nota

Si tiene previsto publicar el complemento en AppSource y que est? disponible en la experiencia de Office, aseg?rese de que se ajusta a las directivas de validaci?n de AppSource. Por ejemplo, para superar la validaci?n, el complemento debe funcionar en todas las plataformas que sean compatibles con los m?todos especificados (para m?s informaci?n, consulte la secci?n 4.12 y el host del complemento de Office y la p?gina de disponibilidad).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).

Componentes de un complemento de OfficeComponents of an Office Add-in

Los complementos están formados por dos componentes básicos:Add-ins consist of two basic components:

  • Una aplicación web formada por una página web y los archivos necesarios de JavaScript, CSS o de otro tipo.A web application consisting of a webpage and any required JavaScript, CSS, or other files. Estos archivos se hospedan en un servidor web o un servicio de hospedaje de sitios web, como Microsoft Azure.These files are hosted on a web server or web hosting service, such as Microsoft Azure. En OneNote en la web, la aplicación web se muestra en un control de explorador o iframe.In OneNote Online, the web application displays in a browser control or iframe.

  • Un manifiesto XML que especifica la URL de la página web del complemento y todos los requisitos de acceso, configuraciones y funciones del complemento. Este archivo se almacena en el cliente. Los complementos de OneNote usan el mismo formato de manifiesto que otros complementos de 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.

Complemento de Office = manifiesto + página webOffice Add-in = Manifest + Webpage

Un complemento de Office está formado por un manifiesto y una página web

Uso de la API de JavaScriptUsing the JavaScript API

Los complementos usan el contexto de tiempo de ejecución de la aplicación host para tener acceso a la API de JavaScript. La API tiene dos capas:Add-ins use the runtime context of the host application to access the JavaScript API. The API has two layers:

  • Una API específica del host para operaciones específicas de OneNote a la que se tiene acceso a través del objeto Application.A host-specific API for OneNote-specific operations, accessed through the Application object.
  • Una API común que se comparte con todas las aplicaciones de Office y a la que se tiene acceso a través del objeto Document.A Common API that's shared across Office applications, accessed through the Document object.

Acceso a la API específica del host a través del objeto ApplicationAccessing the host-specific API through the Application object

Use el objeto Application para tener acceso a objetos de OneNote como Notebook, Section y Page. Con las API específicas del host, puede ejecutar operaciones por lotes en objetos de proxy. El flujo básico sería parecido a este:Use the Application object to access OneNote objects such as Notebook, Section, and Page. With host-specific APIs, you run batch operations on proxy objects. The basic flow goes something like this:

  1. Obtener la instancia de la aplicación desde el contexto.Get the application instance from the context.

  2. Crear un proxy que representa el objeto de OneNote con el que quiere trabajar. Interactuar de forma sincrónica con los objetos del proxy con operaciones de lectura y escritura en propiedades y con llamadas a sus métodos.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. Realice una llamada a load en el proxy para rellenarla con los valores especificados de la propiedad en el parámetro. Esta llamada se agrega a la cola de comandos.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.

    Nota

    Las llamadas del método a la API (como context.application.getActiveSection().pages;) también se agregan a la cola.Method calls to the API (such as context.application.getActiveSection().pages;) are also added to the queue.

  4. Realice una llamada a context.sync para ejecutar todos los comandos en cola en el orden en que se agregaron a la cola. Esto sincroniza el estado entre el script que se ejecuta y los objetos reales, y al recupera las propiedades de los objetos de OneNote cargados para su uso en el script. Puede usar el objeto de compromiso devuelto para encadenar acciones adicionales.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.

Por ejemplo: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));
                }
            });
    });
}

Consulte los objetos y operaciones de OneNote compatibles en la referencia de la API.You can find supported OneNote objects and operations in the API reference.

Conjuntos de requisitos de la API de JavaScript de OneNoteOneNote JavaScript API requirement sets

Los conjuntos de requisitos son grupos de miembros de la API con nombre.Requirement sets are named groups of API members. Los complementos de Office usan los conjuntos de requisitos especificados en el manifiesto o usan una comprobación en tiempo de ejecución para determinar si un host de Office admite las API necesarias para el complemento.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. Para obtener información detallada sobre los conjuntos de requisitos de la API de JavaScript de OneNote, consulte Conjuntos de requisitos de la API de JavaScript de OneNote.For detailed information about OneNote JavaScript API requirement sets, see the OneNote JavaScript API requirement sets article.

Acceso a la API común a través del objeto DocumentAccessing the Common API through the Document object

Use el objeto Document para tener acceso a la API común, como los métodos getSelectedDataAsync y setSelectedDataAsync.Use the Document object to access the Common API, such as the getSelectedDataAsync and setSelectedDataAsync methods.

Por ejemplo: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);
        });
}

Los complementos de OneNote solo son compatibles con las siguientes API comunes:OneNote add-ins support only the following Common APIs:

APIAPI NotasNotes
Office.context.document.getSelectedDataAsyncOffice.context.document.getSelectedDataAsync Office.CoercionType.Text y Office.CoercionType.Matrix soloOffice.CoercionType.Text and Office.CoercionType.Matrix only
Office.context.document.setSelectedDataAsyncOffice.context.document.setSelectedDataAsync Office.CoercionType.Text, Office.CoercionType.Image y Office.CoercionType.Html soloOffice.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); Las opciones de configuración solo son compatibles con complementos de contenidoSettings are supported by content add-ins only
Office.context.document.settings.set(name, value);Office.context.document.settings.set(name, value); Las opciones de configuración solo son compatibles con complementos de contenidoSettings are supported by content add-ins only
Office.EventType.DocumentSelectionChangedOffice.EventType.DocumentSelectionChanged

En general, solo se usa la API común para realizar una acción que no es compatible con la API específica del host. Para obtener más información sobre el uso de la API común, vea la documentación y la referencia de Complementos de Office.In general, you only use the Common API to do something that isn't supported in the host-specific API. To learn more about using the Common API, see the Office Add-ins documentation and reference.

Diagrama del modelo de objetos de OneNoteOneNote object model diagram

En el diagrama siguiente se representa lo que está disponible actualmente en la API de JavaScript de OneNote.The following diagram represents what's currently available in the OneNote JavaScript API.

Diagrama del modelo de objetos de OneNote

Recursos adicionalesSee also