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

Artigo
05/20/2023

O OneNote introduz uma API do JavaScript para suplementos do OneNote na Web. Você pode criar suplementos de painel de tarefas e de conteúdo e comandos de suplemento que interagem com objetos do OneNote e conectam-se a serviços Web ou a outros recursos baseados na Web.

Observação

Se você planeja publicar o seu suplemento no AppSource e disponibilizá-lo na experiência do Office, certifique-se de que está em conformidade com as políticas de certificação do Marketplace Comercial. Por exemplo, para passar na validação, o suplemento deve funcionar em todas as plataformas com suporte para os métodos definidos (saiba mais na seção 1120.3 e na página de aplicativo e disponibilidade do Suplemento do Office).

Componentes de um suplemento do Office

Os suplementos consistem de dois componentes básicos:

Um aplicativo Web consiste em uma página da Web e em JavaScript, CSS ou outros arquivos necessários. Estes arquivos podem ser hospedados em qualquer servidor Web ou serviço de hospedagem na Web, como o Microsoft Azure. Em OneNote na Web, o aplicativo Web é exibido em um controle de webview ou iframe.
Um manifesto XML que especifica a URL da página da Web do suplemento e os requisitos de acesso, as configurações e os recursos para o suplemento. Este arquivo é armazenado no cliente. Os suplementos do OneNote usam o mesmo formato de manifesto como outros suplementos do Office.

Suplemento do Office = Manifesto + Página da Web

Um suplemento do Office consiste em um manifesto e uma página da Web.

Usar a API JavaScript

Os suplementos usam o contexto de runtime do aplicativo do Office para acessar a API JavaScript. A API tem duas camadas:

Uma API específica do aplicativo para operações específicas do OneNote, acessada por meio do objeto Application.
Uma API comum compartilhada entre aplicativos do Office, acessada por meio do objeto Document.

Acessar uma API específica do aplicativo por meio do objeto Aplicativo.

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 será semelhante a:

Obtenha a instância do aplicativo do contexto.
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.
Chame load o proxy para preenchê-lo 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.
Chame context.sync para executar todos os comandos enfileirados na ordem em que foram enfileirados. 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.

Acessar a API comum por meio 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.

API	Observações
Office.context.document.getSelectedDataAsync	Somente `Office.CoercionType.Text` e `Office.CoercionType.Matrix`
Office.context.document.setSelectedDataAsync	Somente `Office.CoercionType.Text`, `Office.CoercionType.Image` e `Office.CoercionType.Html`
const mySetting = Office.context.document.settings.get(name);	As configurações são compatíveis apenas com os suplementos de conteúdo
Office.context.document.settings.set(nome, valor);	As configurações são compatíveis apenas com os suplementos de conteúdo
Office.EventType.DocumentSelectionChanged	Nenhum.

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 usar a API comum, confira Modelo do objeto do JavaScript API para Office.

Diagrama do modelo de objeto do OneNote

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

Diagrama do modelo de objeto do OneNote.