共通 JavaScript API オブジェクト モデル

Office JavaScript API を使用すると、Office クライアント アプリケーションの基になる機能にアクセスできます。 このアクセスの大部分はいくつかの重要なオブジェクトを通過します。 Context オブジェクトによって、初期化した後、ランタイム環境にアクセスできるようになります。 Document オブジェクトによって、Excel、PowerPoint、Word ドキュメントを操作する許可が与えられます。 Mailbox オブジェクトは、メッセージ、予定、およびユーザー プロファイルへのアクセス権を Outlook アドインに付与します。 これらの大まかなオブジェクト間の関係を理解することは、Office アドインの基礎です。

Context オブジェクト

適用対象: すべてのアドインの種類

アドインが初期化されると、ランタイム環境でやり取りできるさまざまなオブジェクトが多数あります。 アドインのランタイム コンテキストは Context オブジェクトによって API で反映されます。 Context は、Document オブジェクトや Mailbox オブジェクトなど、API の最重要オブジェクトにアクセスできるメイン オブジェクトです。最重要オブジェクトはさらにドキュメントやメールボックスのコンテンツにアクセスできます。

たとえば、作業ウィンドウ アドインまたはコンテンツ アドインにおいて、Context オブジェクトの document プロパティを使用して、Document オブジェクトのプロパティおよびメソッドにアクセスし、Word 文書、Excel ワークシート、または Project スケジュールのコンテンツとやり取りできます。 同様に、Outlook アドインにおいて、Context オブジェクトの mailbox プロパティを使用して、Mailbox オブジェクトのプロパティおよびメソッドにアクセスし、メッセージ、会議出席依頼または予定のコンテンツとやり取りできます。

Context オブジェクトは contentLanguage プロパティと displayLanguage プロパティへのアクセスも提供します。このプロパティを使用すると、ドキュメントまたはアイテム、または Office アプリケーションで使用されるロケール (言語) を決定できます。 roamingSettings プロパティによって、RoamingSettings オブジェクトのメンバーにアクセスできます。このオブジェクトによって、個々のユーザーのメールボックスに対してアドインに固有の設定が保存されます。 最後に、Context オブジェクトの ui プロパティを使用すると、アドインでポップアップ ダイアログを開始できます。

Document オブジェクト

適用対象: コンテンツ アドインおよび作業ウィンドウ アドインの種類

Excel、PowerPoint、および Word のドキュメント データを操作するために、API には Document オブジェクトが用意されています。 Document オブジェクト メンバーを使用して、次の方法でデータにアクセスできます。

• テキスト、隣接するセル (マトリックス)、またはテーブルの形式のアクティブな選択範囲への読み取りと書き込み。

• 表形式のデータ (マトリックスまたはテーブル)。

• バインド ( Bindings オブジェクトの "add" メソッドで作成されます)。

• カスタム XML パーツ (Word の場合のみ)。

• ドキュメント上のアドインごとに保持する設定またはアドインの状態。

Document オブジェクトを使用して、Project ドキュメント内のデータを操作することもできます。 API の Project 固有の機能については、ProjectDocument 抽象クラスのメンバー内に説明文があります。 Project 用の作業ウィンドウ アドインの作成の詳細については、「Project 用の作業ウィンドウ アドイン」を参照してください。

これらすべての形式のデータ アクセスは、抽象 Document オブジェクトのインスタンスから開始されます。

作業ウィンドウまたはコンテンツ アドインが初期化されるときに、Context オブジェクトの document プロパティを使用して、Document オブジェクトのインスタンスにアクセスできます。 Document オブジェクトは、Word ドキュメントと Excel ドキュメント間で共有される一般的なデータ アクセス方法を定義し、ドキュメントのCustomXmlParts Word オブジェクトへのアクセスも提供します。

Document オブジェクトでは、開発者がドキュメントコンテンツにアクセスするための 4 つの方法がサポートされています。

• 選択範囲ベースのアクセス

• バインドベースのアクセス

• カスタム XML パーツベースのアクセス (Word の場合のみ)

• ドキュメント全体へのアクセス (PowerPoint および Word のみ)

選択範囲ベースおよびバインドベースのデータ アクセス方法のしくみを理解するために、まず、データ アクセス API が、異なる Office アプリケーション間で一貫性のあるデータ アクセスを提供する方法について説明します。

Office アプリケーション間での一貫性のあるデータ アクセス

適用対象: コンテンツ アドインおよび作業ウィンドウ アドインの種類

Office JavaScript API は、さまざまな Office ドキュメント間でシームレスに機能する拡張機能を作成するために、一般的なデータ型を使用して各 Office アプリケーションの特異性を抽象化し、異なるドキュメント コンテンツを 3 つの一般的なデータ型に強制する機能を提供します。

共通のデータ型

選択範囲ベースとバインドベースのどちらのデータ アクセスでも、ドキュメント コンテンツは、サポートされているすべての Office アプリケーション間で共通のデータ型を通じて公開されます。 3 つのメインデータ型がサポートされています。

データ型の強制型変換

Document オブジェクトと Binding オブジェクトのデータ アクセス メソッドでは、これらのメソッドの coercionType パラメーターと対応する CoercionType 列挙値を使用して、目的のデータ型を指定できます。 バインドの実際の形状にかかわらず、さまざまな Office アプリケーションでは、要求されるデータ型にデータを強制的に型変換することによって、共通のデータ型をサポートします。 たとえば、Word の表または段落が選択されている場合、開発者はそれをプレーン テキスト、HTML、Office Open XML、または表として読み取ることを指定でき、API 実装によって必要な変換やデータ変換が行われます。

指定された型にデータを強制的に型変換できない場合は、コールバック内の AsyncResult.status プロパティが "failed" を返すため、AsyncResult.error プロパティを使用して Error オブジェクトにアクセスし、メソッド呼び出しが失敗した理由を確認できます。

Document オブジェクトを使用して選択範囲を操作する

Document オブジェクトは、ユーザーの現在の選択範囲を "取得して設定" する方法で読み書きできるメソッドを公開します。 これを行うために、 Document オブジェクトは、 getSelectedDataAsync メソッドと setSelectedDataAsync メソッドを提供します。

選択範囲に関する操作の実行方法を示すコード例については、「ドキュメントまたはスプレッドシート内のアクティブな選択範囲へのデータの読み取りおよび書き込み」を参照してください。

Bindings オブジェクトと Binding オブジェクトを使用してバインドを操作する

バインドベースのデータ アクセスを使用すると、コンテンツ アドインおよび作業ウィンドウ アドインで、バインドに関連付けられた識別子を介して、ドキュメントまたはスプレッドシートの特定の領域に一貫性のあるアクセスが可能になります。 アドインは、最初に、ドキュメントの部分と一意の ID を関連付けるメソッドのいずれか (addFromPromptAsync、addFromSelectionAsync、または addFromNamedItemAsync) を呼び出すことによって、バインドを確立する必要があります。 バインドが確立されると、アドインは提供された ID を使用して、ドキュメントまたはスプレッドシート内の関連付けられた領域に含まれるデータにアクセスできます。 バインドを作成すると、アドインに次の値が提供されます。

• 表、範囲、またはテキスト (隣接する一連の文字) など、サポートされている Office アプリケーション全体に共通のデータ構造へのアクセスを許可します。

• ユーザーによる選択を必要とせずに、読み取り/書き込み操作ができます。

• アドインとドキュメント内のデータの間にリレーションシップが確立されます。 バインドはドキュメント内に保持され、後でアクセスできます。

また、バインドを確立すると、ドキュメントまたはスプレッドシートの特定の領域を範囲とする、データおよび選択範囲の変更イベントをサブスクライブできます。 つまり、ドキュメントまたはスプレッドシート全体の全般的な変更ではなく、バインドされた領域内で発生する変更のみがアドインに通知されます。

Bindings オブジェクトが公開している getAllAsync メソッドを使用すると、ドキュメントまたはスプレッドシートで確立されている一連のすべてのバインドにアクセスできます。 個々のバインドには、 Bindings.getBindingByIdAsync メソッドまたは Office.select 関数を使用して、その ID でアクセスできます。 Bindings オブジェクトの addFromSelectionAsync、addFromPromptAsync、addFromNamedItemAsync、または releaseByIdAsync のいずれかのメソッドを使用して、新しいバインドを確立したり、既存のバインドを削除することができます。

addFromSelectionAsync、addFromPromptAsync、または addFromNamedItemAsync メソッドを使用してバインドを作成するときに、bindingType パラメーターで指定するバインドには 3 種類あります。

Bindings オブジェクトの 3 つの "追加" メソッドのいずれかを使用してバインドを作成した後、対応するオブジェクトのメソッド MatrixBinding、TableBinding、または TextBinding を使用して、バインドのデータとプロパティを操作できます。 これらの 3 つのオブジェクトはすべて、バインドされたデータとの対話を可能にするBinding オブジェクトの getDataAsync メソッドと setDataAsync メソッドを継承します。

バインドに関する操作の実行方法を示すコード例については、「ドキュメントまたはスプレッドシート内の領域へのバインド」を参照してください。

CustomXmlParts オブジェクトと CustomXmlPart オブジェクトを使用してカスタム XML パーツを操作する

適用対象: Word の作業ウィンドウ アドイン

API の CustomXmlParts オブジェクトと CustomXmlPart オブジェクトを使用すると、Word 文書内のカスタム XML パーツにアクセスできます。これにより、文書のコンテンツに対する XML 主導の操作が可能になります。 CustomXmlParts オブジェクトとCustomXmlPart オブジェクトの操作のデモについては、Word-add-in-Work-with-custom-XML-parts コード サンプルを参照してください。

getFileAsync メソッドを使用してドキュメント全体を操作する

適用対象: Word および PowerPoint の作業ウィンドウ アドイン

Document.getFileAsync メソッド、および File オブジェクトと Slice オブジェクトのメンバーは、一度に最大で 4 MB ずつのスライス (チャンク) に分割して Word および PowerPoint ドキュメント ファイル全体を取得する機能を提供します。 詳細については、「PowerPoint または Word 用アドインからドキュメント全体を取得する」を参照してください。

Mailbox オブジェクト

適用対象: Outlook アドイン

Outlook アドインでは、主に Mailbox オブジェクトにより公開されている API のサブセットを使用します。 Item オブジェクトなど、Outlook アドインで特に使用するオブジェクトとメンバーにアクセスするには、次のコード行に示すように、Context オブジェクトの mailbox プロパティを使用して Mailbox オブジェクトにアクセスします。

// Access the Item object.
const item = Office.context.mailbox.item;

さらに、Outlook アドインでは、次のオブジェクトを使用できます。

• Office オブジェクト: 初期化に使用します。

• Context オブジェクト: コンテンツおよび表示言語のプロパティへのアクセスに使用します。

Outlook アドインでの JavaScript の使用については、「 Outlook アドイン」を参照してください。Outlook JavaScript API を調べるには、 Outlook API リファレンス ページを参照してください。