OneNote JavaScript API のプログラミングの概要OneNote JavaScript API programming overview

OneNote では、OneNote Online アドインの JavaScript API が導入されています。OneNote オブジェクトを操作する作業ウィンドウ アドイン、コンテンツ アドイン、アドイン コマンドを作成し、Web サービスや他の 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.

注意

AppSource にアドインを公開し、Office エクスペリエンスで利用できるようにする予定がある場合は、AppSource の検証ポリシーに準拠していることを確認してください。たとえば、検証に合格するためには、定義したメソッドをサポートするすべてのプラットフォームでアドインが動作する必要があります (詳細については、セクション 4.12Office アドインを使用できるホストおよびプラットフォームのページを参照してください)。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).

Office アドインのコンポーネントComponents of an Office Add-in

アドインは、2 つの基本コンポーネントで構成されます。Add-ins consist of two basic components:

  • Web ページと必要な任意の JavaScript、CSS、他のファイルを含む Web アプリケーション。これらのファイルは、Web サーバーか、Microsoft Azure などの Web ホスティング サービスでホストされます。OneNote Online では、Web アプリケーションはブラウザー コントロールや iFrame で表示されます。A web application consisting of a webpage and any required JavaScript, CSS, or other files. These files are hosted on a web server or web hosting service, such as Microsoft Azure. In OneNote Online, the web application displays in a browser control or iframe.

  • アドインの Web ページの URL とアドインの任意のアクセス要件、設定、機能を指定する XML マニフェスト。このファイルは、クライアントに保存されます。OneNote アドインは、他の 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.

Office アドイン = マニフェスト + Web ページOffice Add-in = Manifest + Webpage

Office アドインはマニフェストと Web ページによって構成されます

JavaScript API の使用Using the JavaScript API

アドインは、ホスト アプリケーションのランタイム コンテキストを使って、JavaScript API にアクセスします。API には次の 2 つの階層があります。Add-ins use the runtime context of the host application to access the JavaScript API. The API has two layers:

  • アプリケーション オブジェクトを通してアクセスされる、OneNote 固有の操作のための豊富な APIA rich API for OneNote-specific operations, accessed through the Application object.
  • ドキュメント オブジェクトを通してアクセスされ、Office アプリケーション全体で共有される共通 APIA common API that's shared across Office applications, accessed through the Document object.

アプリケーション オブジェクトを使った豊富な API へのアクセスAccessing the rich API through the Application object

アプリケーション オブジェクトを使って、ノートブックセクションページなどの OneNote オブジェクトにアクセスします。豊富な API を使うと、プロキシ オブジェクトでバッチ操作を実行できます。基本的な流れは、以下のようになります。Use the Application object to access OneNote objects such as Notebook, Section, and Page. With rich APIs, you run batch operations on proxy objects. The basic flow goes something like this:

  1. コンテキストからアプリケーション インスタンスを取得します。Get the application instance from the context.

  2. 操作する OneNote オブジェクトを表すプロキシを作成します。プロキシ オブジェクトのプロパティの読み取りや書き込みを行い、メソッドを呼び出すことにより、プロキシ オブジェクトを同期的に操作します。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. プロキシで読み込みを呼び出し、パラメータで指定されたプロパティ値を設定します。この呼び出しは、コマンドのキューに追加されます。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.

    注意

    API へのメソッドの呼び出し (context.application.getActiveSection().pages; など) も、キューに追加されます。Method calls to the API (such as context.application.getActiveSection().pages;) are also added to the queue.

  4. キューに置かれたすべてのコマンドをキューに置かれた順序で実行するには、context.sync を呼び出します。これにより、実行中のスクリプトと実際のオブジェクトの間の状態が同期されます。また、読み込まれた OneNote オブジェクトのプロパティを取得して、スクリプトで使えるようにします。追加のアクションのチェーン処理には、返された約束オブジェクトを使うことができます。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.

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

API リファレンスでは、サポートされている OneNote オブジェクトと操作を見つけることができます。You can find supported OneNote objects and operations in the API reference.

ドキュメント オブジェクトを使った共通 API へのアクセスAccessing the common API through the Document object

ドキュメント オブジェクトを使って、getSelectedDataAsync メソッドや setSelectedDataAsync メソッドなどの共通 API にアクセスします。Use the Document object to access the common API, such as the getSelectedDataAsync and setSelectedDataAsync methods.

例: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 アドインは、次の共通 API のみをサポートします。OneNote add-ins support only the following common APIs:

APIAPI メモNotes
Office.context.document.getSelectedDataAsyncOffice.context.document.getSelectedDataAsync Office.CoercionType.TextOffice.CoercionType.Matrix のみOffice.CoercionType.Text and Office.CoercionType.Matrix only
Office.context.document.setSelectedDataAsyncOffice.context.document.setSelectedDataAsync Office.CoercionType.TextOffice.CoercionType.ImageOffice.CoercionType.Html のみOffice.CoercionType.Text, Office.CoercionType.Image, and Office.CoercionType.Html only
var mySetting = Office.context.document.settings.get(名前);var mySetting = Office.context.document.settings.get(name); 設定はコンテンツ アドインによってのみサポートされますSettings are supported by content add-ins only
Office.context.document.settings.set(名前, 値);Office.context.document.settings.set(name, value); 設定はコンテンツ アドインによってのみサポートされますSettings are supported by content add-ins only
Office.EventType.DocumentSelectionChangedOffice.EventType.DocumentSelectionChanged

一般に、豊富な API でサポートされていない操作を行う場合は、共通 API のみを使います。共通 API の使用についての詳細は、Office アドインのドキュメントリファレンスをご覧ください。In general, you only use the common API to do something that isn't supported in the rich API. To learn more about using the common API, see the Office Add-ins documentation and reference.

OneNote のオブジェクト モデル ダイアグラムOneNote object model diagram

次の図では、OneNote JavaScript API で現在使用可能なものが示されます。The following diagram represents what's currently available in the OneNote JavaScript API.

OneNote のオブジェクト モデル ダイアグラム

関連項目See also