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

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

注:

アドインを AppSource に 公開 し、Office エクスペリエンス内で利用できるようにする場合は、商用マーケットプレイスの認定ポリシー に準拠していることを確認してください。 たとえば、検証に合格するには、アドインは、定義したメソッドをサポートするすべてのプラットフォーム全体で機能する必要があります (詳細については、セクション 1120.3 と「Office アドイン アプリケーションと可用性」のページを参照してください)。

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

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

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

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

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

JavaScript API の使用

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

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

アプリケーション オブジェクトを使ったアプリケーション固有の 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 の要件セット」を参照してください。

ドキュメント オブジェクトを使った共通 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	メモ
Office.context.document.getSelectedDataAsync	Office.CoercionType.TextOffice.CoercionType.Text と Office.CoercionType.MatrixOffice.CoercionType.Matrix のみ
Office.context.document.setSelectedDataAsync	Office.CoercionType.Text、Office.CoercionType.Image と Office.CoercionType.Html のみ
const mySetting = Office.context.document.settings.get(name);	設定はコンテンツ アドインによってのみサポートされます
Office.context.document.settings.set(name, value);	設定はコンテンツ アドインによってのみサポートされます
Office.EventType.DocumentSelectionChanged	なし。

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

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

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

関連項目

• Office アドインを開発する
• Microsoft 365 開発者プログラムについて学ぶ
• 最初の OneNote アドインをビルドする
• OneNote JavaScript API リファレンス
• Rubric Grader のサンプル
• Office アドイン プラットフォームの概要