コンテンツアドインと作業ウィンドウ アドインに対する Office JavaScript API のサポート

  • [アーティクル]

重要

この記事は、Office 2013 で導入された Office JavaScript API モデルである Common API に適用されます。 これらの API には、複数の種類の Office アプリケーション間で共通の UI、ダイアログ、クライアント設定などの機能が含まれます。 Outlook アドインは、共通 API、特に メールボックス オブジェクトを通じて公開される API のサブセットのみを使用します。

共通 API は、アプリケーション固有の API でサポートされていないシナリオにのみ使用してください。 アプリケーション固有の API ではなく共通 API を使用する場合については、「Office JavaScript API について理解する」を参照してください。

Office JavaScript API を使用して、Office クライアント アプリケーション用の作業ウィンドウアドインまたはコンテンツ アドインを作成できます。 コンテンツと作業ウィンドウのアドインをサポートするオブジェクトとメソッドは、次のように分類されます。

  1. 他の Office アドインと共有される共通オブジェクト。 これらのオブジェクトには、 Office、 Context、 AsyncResult が含まれます。 オブジェクトは Office 、Office JavaScript API のルート オブジェクトです。 オブジェクトは Context 、アドインのランタイム環境を表します。 と Context はどちらもOffice、Office アドインの基本的なオブジェクトです。 オブジェクトは AsyncResult 、ユーザーがドキュメントで選択した内容を読み取るメソッドに getSelectedDataAsync 返されるデータなど、非同期操作の結果を表します。

  2. Document オブジェクト。 コンテンツ アドインと作業ウィンドウ アドインで使用可能な API の大部分は、Document オブジェクトのメソッド、プロパティ、およびイベントを通して公開されます。 コンテンツアドインまたは作業ウィンドウ アドインは、Office.context.document プロパティを使用して Document オブジェクトにアクセスでき、それを介して、Bindings オブジェクトや CustomXmlParts オブジェクト、getSelectedDataAsync、setSelectedDataAsync、getFileAsync メソッドなどのドキュメント内のデータを操作するための API のキー メンバーにアクセスできます。 オブジェクトには Document 、ドキュメントが読み取り専用か編集モードかを判断するための mode プロパティ、現在のドキュメントの URL を取得するための url プロパティ、 Settings オブジェクトへのアクセスも用意されています。 オブジェクトでは DocumentSelectionChanged イベントのイベント ハンドラーの追加もサポートされているため、ユーザーがドキュメント内の選択内容をいつ変更するかを検出できます。

    コンテンツアドインまたは作業ウィンドウ アドインは、DOM 環境とランタイム環境が読み込まれた後 (通常は Office.initialize イベントのイベント ハンドラーで) オブジェクトにアクセスDocumentできます。 アドインが初期化されるときのイベント フローと、DOM とラインタイムが正常に読み込まれたかどうかの確認方法については、「DOM とランタイム環境の読み込み」を参照してください。

  3. 特定の機能を操作するためのオブジェクト。 API の特定の機能を操作するには、次のオブジェクトとメソッドを使用します。

    • Bindings オブジェクトのメソッドを使用して、バインドを作成または取得します。また、Binding オブジェクトのメソッドとプロパティを使用して、データを操作します。

    • CustomXmlParts、CustomXmlPart、および関連するオブジェクトを使用して、Word 文書内のカスタム XML パーツを作成および操作します。

    • File オブジェクトと Slice オブジェクトを使用して、文書全体のコピーを作成し、それをチャンクまたは「スライス」に分割してから、それらのスライスに含まれるデータを読み取りまたは転送します。

    • Settings オブジェクトを使用して、ユーザー設定やアドインの状態などのカスタム データを保存します。

重要

API メンバーの一部は、コンテンツ アドインと作業ウィンドウ アドインをホスト可能なすべての Office アプリケーションでサポートされているわけではありません。サポートされているメンバーを特定するには、次のいずれかを参照してください。

Office クライアント アプリケーション全体での Office JavaScript API のサポートの概要については、「 Office JavaScript API について」を参照してください。

文書、スプレッドシート、またはプレゼンテーションのアクティブな選択範囲の読み取りと書き込み

文書、スプレッドシート、またはプレゼンテーション内のユーザーの現在の選択範囲に対して読み書きをすることができます。 アドインの Office アプリケーションに応じて、Document オブジェクトの getSelectedDataAsync メソッドと setSelectedDataAsync メソッドでパラメーターとして読み取りまたは書き込むデータ構造の種類を指定できます。 たとえば、Word には任意のデータ タイプ (テキスト、HTML、表形式データ、または Office Open XML)、Excel にはテキストと表形式データ、および PowerPoint と Project にはテキストを指定できます。 ユーザーの選択範囲に対する変更を検出するためのイベント ハンドラーを作成することもできます。 次の例では、 メソッドを使用して、選択範囲からテキストとしてデータを getSelectedDataAsync 取得します。

Office.context.document.getSelectedDataAsync(
    Office.CoercionType.Text, function (asyncResult) {
        if (asyncResult.status == Office.AsyncResultStatus.Failed) {
            write('Action failed. Error: ' + asyncResult.error.message);
        }
        else {
            write('Selected data: ' + asyncResult.value);
        }
    });

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

詳細と例については、「ドキュメントやスプレッドシート内のアクティブな選択範囲へのデータの読み取りおよび書き込み」を参照してください。

ドキュメントまたはスプレッドシート内のリージョンにバインドする

メソッドと setSelectedDataAsync メソッドをgetSelectedDataAsync使用して、ドキュメント、スプレッドシート、またはプレゼンテーションでユーザーの現在の選択内容を読み取りまたは書き込むことができます。 ただし、ユーザーに選択を要求せずにアドインの複数の実行セッションに渡って文書内の同じ領域にアクセスする場合は、最初にその領域をバインドする必要があります。 そのバインドした領域に対するデータおよび選択範囲変更イベントにサブスクライブすることもできます。

バインドは、Bindings オブジェクトの addFromNamedItemAsync メソッド、addFromPromptAsync メソッド、または addFromSelectionAsync メソッドを使用して追加できます。 これらのメソッドは、バインド内のデータにアクセスするため、あるいは、データ変更または選択範囲変更イベントにサブスクライブするために使用可能な識別子を返します。

メソッドを使用して、ドキュメント内の現在選択されているテキストにバインドを追加する例を次に Bindings.addFromSelectionAsync 示します。

Office.context.document.bindings.addFromSelectionAsync(
    Office.BindingType.Text, { id: 'myBinding' }, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write('Added new binding with type: ' +
            asyncResult.value.type + ' and id: ' + asyncResult.value.id);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

詳細と例については、「ドキュメントまたはスプレッドシート内の領域へのバインド」を参照してください。

ドキュメント全体を取得する

作業ウィンドウ アドインが PowerPoint または Word で実行される場合は、Document.getFileAsync メソッド、File.getSliceAsync メソッド、および File.closeAsync メソッドを使用して、プレゼンテーションまたは文書全体を取得できます。

を呼び出 Document.getFileAsync すと、 File オブジェクト内のドキュメントのコピーが取得されます。 オブジェクトは File 、 Slice オブジェクトとして表される "チャンク" でドキュメントへのアクセスを提供します。 を呼び出 getFileAsyncすときは、ファイルの種類 (テキスト形式または圧縮された Open Office XML 形式) とスライスのサイズ (最大 4 MB) を指定できます。 オブジェクトの内容にFileアクセスするには、Slice.data プロパティの生データを返す を呼び出File.getSliceAsyncします。 圧縮形式を指定した場合は、ファイル データがバイト配列で返されます。 ファイルを Web サービスに転送する場合は、圧縮生データを base64 エンコード文字列に変換してから送信できます。 最後に、ファイルのスライスの取得が完了したら、 メソッドを File.closeAsync 使用してドキュメントを閉じます。

詳細については、PowerPoint や Word 用のアドインからドキュメント全体を取得する方法を参照してください。

Word ドキュメントのカスタム XML 部分の読み取りと書き込み

Open Office XML ファイル形式とコンテンツ コントロールを使用して、カスタム XML パーツを Word ドキュメントに追加し、XML パーツ内の要素をそのドキュメント内のコンテンツ コントロールにバインドできます。 ドキュメントを開くと、Wordは、バインドされたコンテンツ コントロールを読み取り、カスタム XML パーツのデータを自動的に設定します。 ユーザーはコンテンツ コントロールにデータを書き込むこともできます。また、ユーザーがドキュメントを保存すると、コントロール内のデータがバインドされた XML パーツに保存されます。 Word用の作業ウィンドウ アドインでは、Document.customXmlParts プロパティ、CustomXmlParts、CustomXmlPart、CustomXmlNode オブジェクトを使用して、ドキュメントにデータを動的に読み書きできます。

カスタム XML パーツは名前空間に関連付けることができます。 名前空間内のカスタム XML パーツからデータを取得するには、CustomXmlParts.getByNamespaceAsync メソッドを使用します。

CustomXmlParts.getByIdAsync メソッドを使用して、GUID でカスタム XML パーツにアクセスすることもできます。 カスタム XML パーツを取得したら、CustomXmlPart.getXmlAsync メソッドを使用して XML データを取得します。

ドキュメントに新しいカスタム XML パーツを追加するには、 プロパティを Document.customXmlParts 使用してドキュメント内のカスタム XML パーツを取得し、 CustomXmlParts.addAsync メソッドを呼び出します。

作業ウィンドウ アドインを使用してカスタム XML パーツを管理する方法の詳細については、「Word アドインで Office Open XML を使用するタイミングと方法について」を参照してください。

アドイン設定を保存する

多くの場合、ユーザー設定やアドインの状態など、アドインのカスタム データを保存し、次回、アドインを開いたとき、そのデータにアクセスする必要があります。 一般的な Web プログラミング手法を利用し、ブラウザーの Cookie や HTML 5 Web ストレージなど、そのデータを保存できます。 あるいは、アドインを Excel、PowerPoint、Word で実行する場合、Settings オブジェクトのメソッドを使用できます。 オブジェクトで作成された Settings データは、アドインが挿入されて保存されたスプレッドシート、プレゼンテーション、またはドキュメントに格納されます。 このデータは、それを作成したアドインでのみ利用できます。

ドキュメントが格納されているサーバーへのラウンドトリップを回避するために、オブジェクトで Settings 作成されたデータは実行時にメモリ内で管理されます。 過去に保存した設定データがアドインの初期化時にメモリに読み込まれ、そのデータに対する変更は Settings.saveAsync メソッドを呼び出したときにのみ文書に保存されます。 内部的に、データはシリアル化された JSON オブジェクト内に名前と値のペアとして保存されます。 データのメモリ内コピーに対してアイテムの読み取り、書き込み、および削除を実行するには、Settings オブジェクトの get メソッド、set メソッド、および remove メソッドを使用します。 次のコード行は、themeColor という名前の設定を作成して、その値を 'green' に設定する方法を示しています。

Office.context.document.settings.set('themeColor', 'green');

メソッドと remove メソッドを使用してset作成または削除された設定データは、データのメモリ内コピーに対して動作するため、アドインが操作しているドキュメントに設定データの変更を保持するには、 を呼び出saveAsyncす必要があります。

オブジェクトのメソッドを使用したカスタム データの操作の詳細については、「アドインの状態と設定のSettings永続化」を参照してください。

アクセス許可モデルとガバナンス

アドインでは、マニフェストの 要素を Permissions 使用して、Office JavaScript API から必要な機能レベルにアクセスするためのアクセス許可を要求します。 たとえば、アドインでドキュメントへの読み取り/書き込みアクセスが必要な場合、そのマニフェストは、そのPermissions要素のテキスト値としてを指定ReadWriteDocumentする必要があります。 アクセス許可はユーザーのプライバシーとセキュリティを保護するために存在しているので、ベスト プラクティスとしては、その機能に必要な最低限のアクセス許可を要求することをお勧めします。 次の例は、作業ウィンドウのマニフェストで ReadDocument アクセス許可を要求する方法を示しています。

<?xml version="1.0" encoding="utf-8"?>
<OfficeApp xmlns="http://schemas.microsoft.com/office/appforoffice/1.0"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
 xsi:type="TaskPaneApp">
???<!-- Other manifest elements omitted. -->
  <Permissions>ReadDocument</Permissions>
???
</OfficeApp>

詳細については、「 アドインでの API の使用に対するアクセス許可の要求」を参照してください。

関連項目