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

重要

この記事は、Office 2013 で導入された Office JavaScript API モデルである 共通 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 のアドインの実行時コンテキストを反映します。 コンテキストは、ドキュメント オブジェクトやメールボックス オブジェクトなど、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 のプロジェクト固有の機能は、 ProjectDocument 抽象クラスのメンバーに文書化されています。 Project 用の作業ウィンドウ アドインの作成の詳細については、「Project 用の作業ウィンドウ アドイン」を参照してください。

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

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

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

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

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

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

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

選択ベースとバインドベースのデータ アクセス方法のしくみを理解できるように、この記事ではまず、データ アクセス API によってさまざまな Office アプリケーション間で一貫したデータ アクセスを提供する方法について説明します。

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

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

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

共通のデータ型

選択範囲ベースとバインドベースのどちらのデータ アクセスでも、ドキュメント コンテンツは、サポートされているすべての 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 オブジェクトは、headers プロパティと rows プロパティを通じてデータを公開します。	テーブル データ アクセスは、Excel と Word でのみサポートされています。

データ型の強制型変換

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

ヒント

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

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

ドキュメント オブジェクトを使用して選択範囲を操作する

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 パラメーターを使用してバインドの種類を指定します。

バインドの種類	説明	ホスト アプリケーションのサポート
テキスト バインド	テキストとして表現できるドキュメントの領域にバインドします。	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 オブジェクトは、headers プロパティと "行" プロパティを使用してデータを公開します。	Excel または Word の表はすべて、テーブル バインドの基礎にできます。 テーブル バインドを確立すると、ユーザーが表に追加する新しい各行または各列が、自動的にバインドに含まれます。

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

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

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

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

API の CustomXmlParts オブジェクトと CustomXmlPart オブジェクトを使用すると、Word 文書内のカスタム XML パーツにアクセスできます。これにより、文書のコンテンツに対する XML 主導の操作が可能になります。 詳細については、「Excel と Word のカスタム XML データ」を参照してください。

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

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

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

Mailbox オブジェクト

適用対象: Outlook アドイン

Outlook アドインでは、主に Mailbox オブジェクトにより公開されている API のサブセットを使用します。 作成モードまたは読み取りモードの Item オブジェクトなど、Outlook アドインで使用するオブジェクトとメンバーにアクセスするには、Context オブジェクトの Mailbox プロパティを使用して Mailbox オブジェクトにアクセスします。 以下にコードの例を示します。

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

重要

メッセージで Office.context.mailbox.item を呼び出すときは、Outlook クライアントの閲覧ウィンドウがオンになっている必要があることに注意してください。 閲覧ウィンドウを構成する方法については、「 閲覧ウィンドウを使用してメッセージをプレビューする」を参照してください。

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

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

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

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