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

OneNote JavaScript API を使用すると、OneNote on the webを拡張するアドインを構築できます。 作業ウィンドウ アドイン、コンテンツ アドイン、および OneNote オブジェクトと対話し、Web サービスやその他のリソースに接続するアドイン コマンドを作成できます。

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

Office アドインには、次の 2 つの主要なコンポーネントがあります。

• Web ページと必要な JavaScript、CSS、またはその他のファイルを含む Web アプリケーション 。 これらのファイルは、Web サーバーか、Microsoft Azure などの Web ホスティング サービスでホストされます。 OneNote on the webでは、Web アプリケーションは Webview コントロールまたは iframe に表示されます。

• アドインの Web ページの URL と、アドインのアクセス要件、設定、機能を指定する マニフェスト 。 このファイルは、クライアントに保存されます。 OneNote アドインでは、 アドインのみのマニフェスト 形式が使用されます。

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

JavaScript API の使用

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

• Application オブジェクトを介してアクセスされる OneNote 固有の操作用のアプリケーション固有の API。
• Document オブジェクトを通じてアクセスされ、Office アプリケーション全体で共有される共通 API。

Application オブジェクトを使用してアプリケーション固有の API にアクセスする

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

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

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

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

   注:

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

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

例:

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

OneNote JavaScript API の load/sync パターンとその他の一般的なプラクティスの詳細については、「アプリケーション固有の API モデルの使用」を参照してください。

API リファレンスでは、サポートされている OneNote オブジェクトと操作を見つけることができます。

OneNote JavaScript API の要件セット

要件セットは、API メンバーの名前付きグループです。 Office アドインでは、マニフェストで指定されている要件セットを使用するか、ランタイム チェックを使用して、Office アプリケーションがアドインに必要な API をサポートしているかどうかを判断します。 OneNote JavaScript API 要件セットの詳細については、「OneNote JavaScript API の要件セット」を参照してください。

Document オブジェクトを使用して Common API にアクセスする

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

次に例を示します。

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

OneNote アドインは、次の共通 API のみをサポートします。

一般に、アプリケーション固有の API でサポートされていない操作を行う場合は、共通 API を使用します。 Common API の使用の詳細については、「 Common JavaScript API オブジェクト モデル」を参照してください。

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

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

関連項目

• Office アドインを開発する
• 最初の OneNote アドインをビルドする
• OneNote JavaScript API リファレンス
• サンプル: OneNote on the web用ルーブリック グレーダー作業ウィンドウ アドイン