Visão geral da programação da API JavaScript do OneNoteOneNote JavaScript API programming overview

O OneNote introduz uma API do JavaScript para suplementos do OneNote na Web.OneNote introduces a JavaScript API for OneNote add-ins on the 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.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.

Observação

Caso pretenda publicar o suplemento na experiência do Office depois de criá-lo, verifique se você está em conformidade com as Políticas de validação do AppSource. Por exemplo, para passar na validação, seu suplemento deve funcionar em todas as plataformas com suporte aos métodos que você definir (para mais informações, confira a seção 4.12 e a Página de hospedagem e disponibilidade de suplementos do Office).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 um suplemento do OfficeComponents of an Office Add-in

Os suplementos consistem de dois componentes básicos:Add-ins consist of two basic components:

  • Um aplicativo Web consiste em uma página da Web e em JavaScript, CSS ou outros arquivos necessários.A web application consisting of a webpage and any required JavaScript, CSS, or other files. Estes arquivos podem ser hospedados em qualquer servidor Web ou serviço de hospedagem na Web, como o Microsoft Azure.These files are hosted on a web server or web hosting service, such as Microsoft Azure. No OneNote online, o aplicativo Web exibe um controle de navegação ou iframe.In OneNote Online, the web application displays in a browser control or 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.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.

Suplemento do Office = manifesto + página da WebOffice Add-in = Manifest + Webpage

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

Usar a API JavaScriptUsing the JavaScript API

Os suplementos usam o contexto de tempo de execução do aplicativo host para acessar a API JavaScript. A API tem duas camadas:Add-ins use the runtime context of the host application to access the JavaScript API. The API has two layers:

  • Uma API avançada para operações específicas do OneNote, acessada por meio do objeto Aplicativo.A host-specific API for OneNote-specific operations, accessed through the Application object.
  • Uma API comum compartilhada entre os aplicativos do Office, acessada por meio do objeto Documento.A Common API that's shared across Office applications, accessed through the Document object.

Acessar uma API avançada por meio do objeto Aplicativo.Accessing the host-specific API through the Application object

Use o objeto Aplicativo para acessar os objetos do OneNote, como Bloco de anotações, Seção e Página.Use the Application object to access OneNote objects such as Notebook, Section, and Page. Com as APIs avançadas, você executa operações em lotes em objetos proxy.With host-specific APIs, you run batch operations on proxy objects. O fluxo básico será semelhante a:The basic flow goes something like this:

  1. Obtenha a instância do aplicativo do contexto.Get the application instance from the context.

  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.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. Chame load no proxy para preenchê-lo com valores de propriedade especificados no parâmetro. Essa chamada é adicionada à fila 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.

    Observação

    Chamadas de método para a API (como context.application.getActiveSection().pages;) também são adicionadas à fila.Method calls to the API (such as context.application.getActiveSection().pages;) are also added to the queue.

  4. Chame context.sync para executar todos os comandos na fila na ordem em que eles estão. 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 seu script. Você pode usar o objeto promessa retornado para o encadeamento ações adicionais.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 exemplo: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));
                }
            });
    });
}

Você pode encontrar objetos do OneNote e operações compatíveis na Referência API.You can find supported OneNote objects and operations in the API reference.

Conjuntos de requisitos da API JavaScript do OneNoteOneNote JavaScript API requirement sets

Os conjuntos de requisitos são grupos nomeados de membros da API.Requirement sets are named groups of API members. 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 host do Office oferece suporte para as APIs necessárias para um suplemento.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 saber mais sobre conjuntos de requisitos da API JavaScript do OneNote, consulte Conjuntos de requisitos da API JavaScript do OneNote.For detailed information about OneNote JavaScript API requirement sets, see the OneNote JavaScript API requirement sets article.

Acessar a API comum por meio do objeto DocumentoAccessing the Common API through the Document object

Use o objeto Documento para acessar a API comum, como os métodos getSelectedDataAsync e setSelectedDataAsync.Use the Document object to access the Common API, such as the getSelectedDataAsync and setSelectedDataAsync methods.

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

Os suplementos do OneNote são compatíveis apenas com as seguintes APIs comuns:OneNote add-ins support only the following Common APIs:

APIAPI ObservaçõesNotes
Office.context.document.getSelectedDataAsyncOffice.context.document.getSelectedDataAsync Apenas Office.CoercionType.Text e Office.CoercionType.MatrixOffice.CoercionType.Text and Office.CoercionType.Matrix only
Office.context.document.setSelectedDataAsyncOffice.context.document.setSelectedDataAsync Apenas Office.CoercionType.Text, Office.CoercionType.Image e Office.CoercionType.HtmlOffice.CoercionType.Text, Office.CoercionType.Image, and Office.CoercionType.Html only
var mySetting = Office.context.document.settings.get(nome);var mySetting = Office.context.document.settings.get(name); As configurações são compatíveis apenas com os suplementos de conteúdoSettings are supported by content add-ins only
Office.context.document.settings.set(nome, valor);Office.context.document.settings.set(name, value); As configurações são compatíveis apenas com os suplementos de conteúdoSettings are supported by content add-ins only
Office.EventType.DocumentSelectionChangedOffice.EventType.DocumentSelectionChanged

Em geral, você só pode usar a API comum para fazer algo que não seja compatível com a API avançada.In general, you only use the Common API to do something that isn't supported in the host-specific API. Para saber mais sobre como usar a API comum, confira a documentação e a referência dos suplementos do Office.To learn more about using the Common API, see the Office Add-ins documentation and reference.

Diagrama do modelo de objeto do OneNoteOneNote object model diagram

O diagrama a seguir representa o que está disponível atualmente na API JavaScript do OneNote.The following diagram represents what's currently available in the OneNote JavaScript API.

Diagrama do modelo de objeto do OneNote

Confira tambémSee also