共通 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 クライアント アプリケーションの基になる機能にアクセスできます。 このアクセスの大部分はいくつかの重要なオブジェクトを通過します。 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 して、次の方法でデータにアクセスできます。

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

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

• バインド (オブジェクトの "add" メソッドを使用して Bindings 作成)。

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

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

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

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

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

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

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

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

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

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

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

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

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

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

共通のデータ型

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

データ型	説明	ホスト アプリケーションのサポート
テキスト	選択範囲またはバインド内のデータの文字列表現を提供します。	Excel、Project、PowerPoint では、プレーン テキストのみがサポートされています。 Wordでは、プレーン テキスト、HTML、Office Open XML (OOXML) の 3 つのテキスト形式がサポートされています。 Excel のセル内でテキストが選択されていると (セル内でテキストの一部のみが選択されている場合でも)、選択範囲ベースのメソッドは、セルのコンテンツ全体の読み取りおよび書き込みを行います。 Word および PowerPoint でテキストが選択されていると、選択範囲ベースのメソッドは、選択されている文字の並びのみの読み取りおよび書き込みを行います。 Project と PowerPoint では、選択ベースのデータ アクセスのみがサポートされます。
Matrix	選択範囲またはバインドに含まれるデータを 2 次元の Array として提供します (JavaScript で配列の配列として実装されているものです)。 たとえば、2 つの列にある 2 つ行の string 値は [['a', 'b'], ['c', 'd']] になり、3 つの行を持つ 1 つの列は [['a'], ['b'], ['c']] になります。	マトリックス データ アクセスは、Excel とWordでのみサポートされます。
Table	選択範囲またはバインド内のデータを TableData オブジェクトとして提供します。 オブジェクトはTableData、 プロパティと rows プロパティを使用してデータをheaders公開します。	テーブル データ アクセスは、Excel とWordでのみサポートされます。

データ型の強制型変換

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

ヒント

データ アクセスにマトリックスを使用する場合と、テーブルの coercionType を使用する場合。 行と列を追加するときに表形式データを動的に拡張する必要があり、テーブル ヘッダーを操作する必要がある場合は、テーブル データ型を使用する必要があります (または Binding オブジェクト データ アクセス メソッドの coercionType パラメーターを Document または Office.CoercionType.Tableとして"table"指定します)。 データ構造内の行と列の追加は、テーブルとマトリックス データの両方でサポートされますが、行と列の追加はテーブル データでのみサポートされます。 行と列の追加を計画していない場合、データにヘッダー機能が必要ない場合は、マトリックス データ型 (または として"matrix"Office.CoercionType.Matrixデータ アクセス メソッドの coercionType パラメーターを指定) を使用する必要があります。これは、データとの対話のより簡単なモデルを提供します。

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

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

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

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

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

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

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

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

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

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

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

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

バインドの種類	説明	ホスト アプリケーションのサポート
テキスト バインド	テキストとして表現できるドキュメントの領域にバインドします。	Word では、連続する選択範囲の大部分が有効ですが、Excel では、単一セルの範囲のみがテキスト バインドの対象です。 Excel では、プレーン テキストのみがサポートされます。 Word では、3 つの形式 (プレーン テキスト、HTML、および Open XML for Office) がサポートされます。
マトリックス バインド	ヘッダーがない表形式のデータが含まれるドキュメントの固定領域にバインドします。 マトリックス バインド内のデータは、2 次元 配列として書き込まれるか、読み取られます。JavaScript では配列の配列として実装されます。 たとえば、2 つの列の 2 行の 文字列 値を として [['a', 'b'], ['c', 'd']]書き込んだり、として読み取ったりでき、3 行の 1 つの列を として書き込んだり、 として [['a'], ['b'], ['c']]読み取ったりできます。	Excel では、セルの連続する選択範囲を使用してマトリックス バインドを確立できます。 Word では、表のみがマトリックス バインドをサポートします。
テーブル バインド	ヘッダーがある表が含まれるドキュメントの領域にバインドします。 テーブル バインド内のデータは、TableData オブジェクトとして書き込みまたは読み取りが行われます。 オブジェクトはTableData、ヘッダーと行のプロパティを使用してデータを公開します。	Excel または Word の表はすべて、テーブル バインドの基礎にできます。 テーブル バインドを確立すると、ユーザーが表に追加する新しい各行または各列が、自動的にバインドに含まれます。

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

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

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

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

API の CustomXmlParts オブジェクトと CustomXmlPart オブジェクトを使用すると、Word 文書内のカスタム XML パーツにアクセスできます。これにより、文書のコンテンツに対する XML 主導の操作が可能になります。 オブジェクトと CustomXmlPart オブジェクトの操作CustomXmlPartsのデモについては、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 オブジェクト: コンテンツおよび表示言語のプロパティへのアクセスに使用します。

• RoamingSettings オブジェクト: アドインがインストールされているユーザーのメールボックスに Outlook アドイン固有のカスタム設定を保存する際に使用します。

Outlook アドインでの JavaScript の使用については、「Outlook アドイン」を参照してください。