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

OneNote では、OneNote Online アドインの JavaScript API が導入されています。OneNote オブジェクトを操作する作業ウィンドウ アドイン、コンテンツ アドイン、アドイン コマンドを作成し、Web サービスや他の Web ベースのリソースに接続できます。

注意

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

Office アドインのコンポーネント

アドインは、2 つの基本コンポーネントで構成されます。

  • Web ページと必要な任意の JavaScript、CSS、他のファイルを含む Web アプリケーション。これらのファイルは、Web サーバーか、Microsoft Azure などの Web ホスティング サービスでホストされます。OneNote Online では、Web アプリケーションはブラウザー コントロールや iFrame で表示されます。

  • アドインの Web ページの URL とアドインの任意のアクセス要件、設定、機能を指定する XML マニフェスト。このファイルは、クライアントに保存されます。OneNote アドインは、他の Office アドインと同じマニフェスト形式を使います。

Office アドイン = マニフェスト + Web ページ

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

JavaScript API の使用

アドインは、ホスト アプリケーションのランタイム コンテキストを使って、JavaScript API にアクセスします。API には次の 2 つの階層があります。

  • アプリケーション オブジェクトを通してアクセスされる、OneNote 固有の操作のための豊富な API
  • ドキュメント オブジェクトを通してアクセスされ、Office アプリケーション全体で共有される共通 API

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

アプリケーション オブジェクトを使って、ノートブックセクションページなどの OneNote オブジェクトにアクセスします。豊富な API を使うと、プロキシ オブジェクトでバッチ操作を実行できます。基本的な流れは、以下のようになります。

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

  2. 操作する OneNote オブジェクトを表すプロキシを作成します。プロキシ オブジェクトのプロパティの読み取りや書き込みを行い、メソッドを呼び出すことにより、プロキシ オブジェクトを同期的に操作します。

  3. プロキシで読み込みを呼び出し、パラメーターで指定されたプロパティ値を設定します。この呼び出しは、コマンドのキューに追加されます。

    注意

    API へのメソッドの呼び出し (context.application.getActiveSection().pages; など) も、キューに追加されます。

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

例:

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 オブジェクトと操作を見つけることができます。

ドキュメント オブジェクトを使った共通 API へのアクセス

ドキュメント オブジェクトを使って、getSelectedDataAsync メソッドや setSelectedDataAsync メソッドなどの共通 API にアクセスします。

例:

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 のみをサポートします。

API メモ
Office.context.document.getSelectedDataAsync Office.CoercionType.TextOffice.CoercionType.Matrix のみ
Office.context.document.setSelectedDataAsync Office.CoercionType.TextOffice.CoercionType.ImageOffice.CoercionType.Html のみ
var mySetting = Office.context.document.settings.get(name); 設定はコンテンツ アドインによってのみサポートされます
Office.context.document.settings.set(name, value); 設定はコンテンツ アドインによってのみサポートされます
Office.EventType.DocumentSelectionChanged

一般に、豊富な API でサポートされていない操作を行う場合は、共通 API のみを使います。共通 API の使用について詳しくは、Office アドインのドキュメントリファレンスをご覧ください。

OneNote のオブジェクト モデル図

次の図では、OneNote JavaScript API で現在使用可能なものが示されます。

OneNote のオブジェクト モデル図

関連項目