Introducción a la programación de API de JavaScript para OneNote

Artículo
05/20/2023

OneNote introduce una API de JavaScript para complementos de OneNote en la 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.

Nota:

Si tiene previsto publicar el complemento para AppSource y hacer que esté disponible en la experiencia de Office, asegúrese de que cumple con las Directivas comerciales de certificación de mercado. 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, vea la sección 1120.3 y la página de disponibilidad y aplicación del complemento de Office).

Componentes de un complemento de Office

Los complementos están formados por dos componentes básicos:

Una aplicación web formada por una página web y los archivos necesarios de JavaScript, CSS o de otro tipo. Estos archivos se hospedan en un servidor web o un servicio de hospedaje de sitios web, como Microsoft Azure. En OneNote en la Web, la aplicación web se muestra en un control de vista web o 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.

Complemento de Office = manifiesto + página web

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

Uso de la API de JavaScript

Los complementos usan el contexto en tiempo de ejecución de la aplicación de Office para acceder a la API de JavaScript. La API tiene dos capas:

Una API específica de la aplicación para operaciones específicas de OneNote a la que se tiene acceso a través del objeto Application.
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.

Acceso a la API específica de la aplicación a través del objeto Aplicación

Use el Application objeto para acceder a objetos de OneNote como Notebook, Section y Page. Con las API específicas de la aplicación, se ejecutan operaciones por lotes en objetos proxy. El flujo básico sería parecido a este:

Obtener la instancia de la aplicación desde el contexto.
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.
Llame al load proxy para rellenarlo con los valores de propiedad especificados en el parámetro . Esta llamada se agrega a la cola de comandos.

Nota:

Las llamadas del método a la API (como context.application.getActiveSection().pages;) también se agregan a la cola.
Llame context.sync a para ejecutar todos los comandos en cola en el orden en que se ponen en 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.

Por ejemplo:

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

Consulte Usar el modelo de API específico de la aplicación para obtener más información sobre el patrón de load/sync y otras prácticas comunes de las API de JavaScript de OneNote.

Consulte los objetos y operaciones de OneNote compatibles en la referencia de la API.

Conjuntos de requisitos de la API de JavaScript de OneNote

Los conjuntos de requisitos son grupos de miembros de la API con nombre. 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 una aplicación de Office admite las API necesarias para el complemento. 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.

Acceso a la API común a través del objeto Document

Use el objeto Document para tener acceso a la API común, como los métodos getSelectedDataAsync y setSelectedDataAsync.

Por ejemplo:

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

Los complementos de OneNote solo son compatibles con las siguientes API comunes.

API	Notas
Office.context.document.getSelectedDataAsync	Solo `Office.CoercionType.Text` y `Office.CoercionType.Matrix`
Office.context.document.setSelectedDataAsync	Solo `Office.CoercionType.Text`, `Office.CoercionType.Image` y `Office.CoercionType.Html`
const mySetting = Office.context.document.settings.get(name);	Las opciones de configuración solo son compatibles con complementos de contenido
Office.context.document.settings.set(name, value);	Las opciones de configuración solo son compatibles con complementos de contenido
Office.EventType.DocumentSelectionChanged	Ninguno.

En general, se usa la API común para realizar una acción que no es compatible con la API específica de la aplicación. Para obtener más información sobre cómo usar la API común, consulte Modelo de objetos de API de JavaScript común.

Diagrama del modelo de objetos de OneNote

En el diagrama siguiente se representa lo que está disponible actualmente en la API de JavaScript de OneNote.

Diagrama del modelo de objetos de OneNote.