Übersicht über die JavaScript-API-Programmierung für OneNoteOneNote JavaScript API programming overview

OneNote führt eine JavaScript-API für OneNote-Add-Ins im Web ein.OneNote introduces a JavaScript API for OneNote add-ins on the web. Sie können Aufgabenbereich-Add-Ins, Inhalts-Add-Ins und Add-In-Befehle erstellen, die mit OneNote-Objekten interagieren und eine Verbindung zu Webdiensten oder anderen webbasierten Ressourcen herstellen.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.

Hinweis

Wenn Sie Ihr Add-In in AppSource veröffentlichen und innerhalb der Office-Benutzererfahrung verfügbar machen möchten, vergewissern Sie sich beim Erstellen des Add-Ins, dass es den AppSource-Validierungsrichtlinien entspricht. Damit das Add-In die Validierung besteht, muss es beispielsweise auf allen Plattformen funktionieren, die die Methoden unterstützen, die Sie definieren (weitere Informationen finden Sie im Abschnitt 4.12 und auf der Host- und Verfügbarkeitsseite von Office-Add-Ins).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).

Komponenten eines Office-Add-InsComponents of an Office Add-in

Add-Ins bestehen aus zwei grundlegenden Komponenten:Add-ins consist of two basic components:

  • Einer Webanwendung, die aus einer Webseite und anderen erforderlichen JavaScript-, CSS- oder anderen Dateien besteht.A web application consisting of a webpage and any required JavaScript, CSS, or other files. Diese Dateien werden auf einem Webserver oder auf einem Webhostdienst gehostet, z. B. Microsoft Azure.These files are hosted on a web server or web hosting service, such as Microsoft Azure. In OneNote im Web wird die Webanwendung in einem Browsersteuerelement oder Iframe angezeigt.In OneNote on the web, the web application displays in a browser control or iframe.

  • Einem XML-Manifest, das die URL der Webseite des Add-Ins sowie Zugriffsanforderungen, Einstellungen und Funktionen für das Add-In angibt. Diese Datei wird auf dem Client gespeichert. OneNote-Add-Ins verwenden dasselbe Manifestformat wie andere Office-Add-Ins.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.

Office Add-In = Manifest + WebseiteOffice Add-in = Manifest + Webpage

Ein Office-Add-In besteht aus einem Manifest und einer Webseite

Verwenden der JavaScript-APIUsing the JavaScript API

Add-Ins verwenden den Laufzeitkontext der Hostanwendung, um auf die JavaScript-API zuzugreifen. Die API besteht aus zwei Ebenen:Add-ins use the runtime context of the host application to access the JavaScript API. The API has two layers:

  • Einer hostspezifischen API für OneNote-spezifische Vorgänge, auf die über das Application-Objekt zugegriffen wird.A host-specific API for OneNote-specific operations, accessed through the Application object.
  • Einer allgemeinen API, die über Office-Anwendungen hinweg freigegeben ist und über die über das Document-Objekt zugegriffen wird.A Common API that's shared across Office applications, accessed through the Document object.

Zugreifen auf die hostspezifische API über das Application-ObjektAccessing the host-specific API through the Application object

Verwenden Sie das Application-Objekt, um auf OneNote-Objekte zuzugreifen, z. B. Notebook, Section und Page. Mit hostspezifischen APIs können Sie auf Proxyobjekten Batchvorgänge ausführen. Der grundlegende Fluss sieht ungefähr folgendermaßen aus:Use the Application object to access OneNote objects such as Notebook, Section, and Page. With host-specific APIs, you run batch operations on proxy objects. The basic flow goes something like this:

  1. Rufen Sie die Anwendungsinstanz aus dem Kontext auf.Get the application instance from the context.

  2. Erstellen Sie einen Proxy, der das OneNote-Objekt darstellt, mit dem Sie arbeiten möchten. Sie interagieren synchron mit Proxyobjekten, indem Sie deren Eigenschaften lesen und ihre Methoden aufrufen.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. Rufen Sie load im Proxy auf, um diesen mit den im Parameter angegebenen Eigenschaften zu füllen. Dieser Aufruf wird der Warteschlange von Befehlen hinzugefügt.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.

    Hinweis

    Methodenaufrufe der API (z. B. context.application.getActiveSection().pages;) werden ebenfalls der Warteschlange hinzugefügt.Method calls to the API (such as context.application.getActiveSection().pages;) are also added to the queue.

  4. Rufen Sie context.sync auf, um alle in die Warteschlange eingereihten Befehle in der Reihenfolge auszuführen, in der sie in die Warteschlange gestellt wurden. Dadurch wird der Zustand zwischen dem ausgeführten Skript und den realen Objekten und durch Abrufen von Eigenschaften von geladenen OneNote-Objekten für die Verwendung in Ihrem Skript synchronisiert. Sie können das zurückgegebene promise-Objekt zum Verketten zusätzlicher Aktionen verwenden.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.

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

Die unterstützten OneNote-Objekte und -Vorgänge finden Sie in der API-Referenz.You can find supported OneNote objects and operations in the API reference.

JavaScript-API-Anforderungssätze für OneNoteOneNote JavaScript API requirement sets

Anforderungssätze sind benannte Gruppen von API-Mitgliedern.Requirement sets are named groups of API members. Office-Add-Ins verwenden im Manifest angegebene Anforderungssätze oder ermitteln mithilfe einer Laufzeitüberprüfung, ob ein Office-Host APIs unterstützt, die ein Add-In benötigt.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. Detaillierte Informationen zu JavaScript-API-Anforderungssätzen für OneNote finden Sie im Artikel JavaScript-API-Anforderungssätze für OneNote.For detailed information about OneNote JavaScript API requirement sets, see the OneNote JavaScript API requirement sets article.

Zugreifen auf die allgemeine API über das Document-ObjektAccessing the Common API through the Document object

Verwenden Sie das Document-Objekt, um auf die allgemeine API zuzugreifen, z. b. die Methoden getselecteddataasync und setSelectedDataAsync.Use the Document object to access the Common API, such as the getSelectedDataAsync and setSelectedDataAsync methods.

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

OneNote-Add-Ins unterstützen nur die folgenden allgemeinen APIs:OneNote add-ins support only the following Common APIs:

APIAPI AnmerkungenNotes
Office.context.document.getSelectedDataAsyncOffice.context.document.getSelectedDataAsync Nur Office.CoercionType.Text und Office.CoercionType.MatrixOffice.CoercionType.Text and Office.CoercionType.Matrix only
Office.context.document.setSelectedDataAsyncOffice.context.document.setSelectedDataAsync Nur Office.CoercionType.Text, Office.CoercionType.Image und Office.CoercionType.HtmlOffice.CoercionType.Text, Office.CoercionType.Image, and Office.CoercionType.Html only
var mySetting = Office.context.document.settings.get(name);var mySetting = Office.context.document.settings.get(name); Einstellungen werden nur von Inhalts-Add-Ins unterstützt.Settings are supported by content add-ins only
Office.context.document.settings.set(name, value);Office.context.document.settings.set(name, value); Einstellungen werden nur von Inhalts-Add-Ins unterstützt.Settings are supported by content add-ins only
Office.EventType.DocumentSelectionChangedOffice.EventType.DocumentSelectionChanged

Im Allgemeinen verwenden Sie die allgemeine API nur, um etwas zu tun, was von der hostspezifischen API nicht unterstützt wird. Weitere Informationen zur Verwendung der allgemeinen API finden Sie in der Dokumentation und Referenz der Office-Add-Ins.In general, you only use the Common API to do something that isn't supported in the host-specific API. To learn more about using the Common API, see the Office Add-ins documentation and reference.

OneNote-ObjektmodelldiagrammOneNote object model diagram

Im folgenden Diagramm ist dargestellt, was derzeit in der JavaScript-API für OneNote verfügbar ist.The following diagram represents what's currently available in the OneNote JavaScript API.

OneNote-Objektmodelldiagramm

Siehe auchSee also