Visão geral da programação da API JavaScript do OneNote

A API JavaScript do OneNote permite-lhe criar suplementos que se expandem OneNote na Web. Pode criar suplementos do painel de tarefas, suplementos de conteúdo e comandos de suplementos que interagem com objetos do OneNote e se ligam a serviços Web ou outros recursos.

Componentes de um suplemento do Office

Os Suplementos do Office têm dois componentes principais:

• Uma aplicação Web com uma página Web e quaisquer ficheiros JavaScript, CSS ou outros necessários. Estes arquivos podem ser hospedados em qualquer servidor Web ou serviço de hospedagem na Web, como o Microsoft Azure. No OneNote na Web, a aplicação Web é apresentada num controlo de webview ou iframe.

• Um manifesto que especifica o URL da página Web do suplemento e quaisquer requisitos de acesso, definições e capacidades para o suplemento. Este arquivo é armazenado no cliente. Os suplementos do OneNote utilizam o formato de manifesto apenas de suplemento .

Suplemento do Office = Manifesto + Página da Web

Usar a API JavaScript

Os suplementos utilizam o contexto de runtime da aplicação do Office para aceder à API javaScript. A API tem duas camadas:

• Uma API específica da aplicação para operações específicas do OneNote, acedida através do Application objeto.
• Uma API comum compartilhada entre aplicativos do Office, acessada por meio do objeto Document.

Aceder à API específica da aplicação através do objeto Aplicação

Use o objeto Application para acessar objetos do OneNote, como Bloco de Anotações, Seção e Página. Com APIs específicas do aplicativo, você executa operações em lotes em objetos proxy. O fluxo básico funciona da seguinte forma:

1. Obtenha a instância do aplicativo do contexto.

2. Crie um proxy que representa o objeto do OneNote com o qual você deseja trabalhar. Você interage com sincronia com os objetos proxy lendo e gravar suas propriedades e chamando seus métodos.

3. Chame load o proxy para o preencher com os valores de propriedade especificados no parâmetro . Essa chamada é adicionada à fila de comandos.

   Observação

   Chamadas de método para a API (como context.application.getActiveSection().pages;) também são adicionadas à fila.

4. Chame context.sync para executar todos os comandos em fila pela ordem em que foram em fila. Isso sincroniza o estado entre o momento em que os scripts e os objetos reais estão sendo executados, além de recuperar as propriedades dos objetos do OneNote carregados para uso no script. Você pode usar o objeto de promessa retornado para o encadeamento de ações adicionais.

Por exemplo:

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

Confira Usando o modelo de API específica do aplicativo para saber mais sobre o padrão load/sync e outras práticas comuns nas APIs de JavaScript do OneNote.

Você pode encontrar objetos do OneNote e operações compatíveis na Referência API.

Conjuntos de requisitos da API JavaScript do OneNote

Os conjuntos de requisitos são grupos nomeados de membros da API. Os Suplementos do Office usam conjuntos de requisitos especificados no manifesto ou usam uma verificação de tempo de execução para determinar se um aplicativo do Office oferece suporte para as APIs necessárias para um suplemento. Para saber mais sobre conjuntos de requisitos da API JavaScript do OneNote, consulte Conjuntos de requisitos da API JavaScript do OneNote.

Aceder à API Comum através do objeto Documento

Use o objeto Documentpara acessar a API comum, como os métodos getSelectedDataAsync e setSelectedDataAsync.

Por exemplo:

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

Os suplementos do OneNote dão suporte apenas às APIs comuns a seguir.

Em geral, você usa a API Comum para fazer algo que não é compatível com a API específica do aplicativo. Para obter mais informações sobre como utilizar a API Comum, veja Common JavaScript API object model (Modelo de objetos da API JavaScript Comuns).

Diagrama do modelo de objeto do OneNote

O diagrama a seguir representa o que está disponível atualmente na API JavaScript do OneNote.

Confira também

• Desenvolvimento de Suplementos do Office
• Criar seu primeiro suplemento do OneNote
• Referência da API JavaScript do OneNote
• Exemplo: Suplemento do painel de tarefas do classificador de rubricas para OneNote na Web