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

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.

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.

• Manifiesto que especifica la dirección URL de la página web del complemento y los requisitos de acceso, la configuración y las funcionalidades del complemento. Este archivo se almacena en el cliente. Los complementos de OneNote usan el formato de manifiesto de solo complemento .

Complemento de Office = manifiesto + 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:

1. Obtener la instancia de la aplicación desde el contexto.

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.

3. 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.

4. 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.

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.

Recursos adicionales

• Desarrollo de complementos de Office
• Crear el primer complemento de OneNote
• Referencia de la API de JavaScript de OneNote
• Ejemplo: Calificador de rúbrica