Office JavaScript API オブジェクト モデルOffice JavaScript API object model

Office JavaScript アドインを利用すると、ホストの基本機能にアクセスできます。Office JavaScript add-ins give access to the host’s underlying functionality. このアクセスの大部分はいくつかの重要なオブジェクトを通過します。Most of this access goes through a few important objects. Context オブジェクトによって、初期化した後、ランタイム環境にアクセスできるようになります。The Context object gives access to the runtime environment after initialization. Document オブジェクトによって、Excel、PowerPoint、Word ドキュメントを操作する許可が与えられます。The Document object gives the user control over an Excel, PowerPoint, or Word document. Mailbox オブジェクトによって、Outlook アドインがメッセージやユーザー プロファイルにアクセスできるようになります。The Mailbox object gives an Outlook add-in access to messages and user profiles. このような上位オブジェクト間の関係を理解することが JavaScript アドインの基礎となります。Understanding the relationships between these high-level objects is the foundation of a JavaScript add-in.

Context オブジェクトContext object

適用対象: すべてのアドインの種類Applies to: All add-in types

アドインが初期化されると、ランタイム環境でやり取りできるさまざまなオブジェクトが多数あります。When an add-in is initialized, it has many different objects that it can interact with in the runtime environment. アドインのランタイム コンテキストは Context オブジェクトによって API で反映されます。The add-in's runtime context is reflected in the API by the Context object. Context は、Document オブジェクトや Mailbox オブジェクトなど、API の最重要オブジェクトにアクセスできるメイン オブジェクトです。最重要オブジェクトはさらにドキュメントやメールボックスのコンテンツにアクセスできます。The Context is the main object that provides access to the most important objects of the API, such as the Document and Mailbox objects, which in turn provide access to document and mailbox content.

たとえば、作業ウィンドウ アドインまたはコンテンツ アドインにおいて、Context オブジェクトの document プロパティを使用して、Document オブジェクトのプロパティおよびメソッドにアクセスし、Word 文書、Excel ワークシート、または Project スケジュールのコンテンツとやり取りできます。同様に、Outlook アドインにおいて、Context オブジェクトの mailbox プロパティを使用して、Mailbox オブジェクトのプロパティおよびメソッドにアクセスし、メッセージ、会議出席依頼または予定のコンテンツとやり取りできます。For example, in task pane or content add-ins, you can use the document property of the Context object to access the properties and methods of the Document object to interact with the content of Word documents, Excel worksheets, or Project schedules. Similarly, in Outlook add-ins, you can use the mailbox property of the Context object to access the properties and methods of the Mailbox object to interact with the message, meeting request, or appointment content.

Context オブジェクトからは、contentLanguage プロパティと displayLanguage プロパティにもアクセスできます。これらのプロパティによって、ドキュメント、アイテム、ホスト アプリケーションで使用されるロケール (言語) を決定できます。The Context object also provides access to the contentLanguage and displayLanguage properties that let you determine the locale (language) used in the document or item, or by the host application. roamingSettings プロパティによって、RoamingSettings オブジェクトのメンバーにアクセスできます。このオブジェクトによって、個々のユーザーのメールボックスに対してアドインに固有の設定が保存されます。The roamingSettings property lets you access the members of the RoamingSettings object, which stores settings specific to your add-in for individual users' mailboxes. 最後に、Context オブジェクトの ui プロパティを使用すると、アドインでポップアップ ダイアログを開始できます。Finally, the Context object provides a ui property that enables your add-in to launch pop-up dialogs.

Document オブジェクトDocument object

適用対象: コンテンツ アドインおよび作業ウィンドウ アドインの種類Applies to: Content and task pane add-in types

Excel、PowerPoint、および Word のドキュメント データを操作するために、API には Document オブジェクトが用意されています。Document オブジェクトのメンバーを使用すると、次のようにデータにアクセスできます。To interact with document data in Excel, PowerPoint, and Word, the API provides the Document object. You can use Document object members to access data from the following ways:

  • テキスト、隣接するセル (マトリックス)、またはテーブルの形式のアクティブな選択範囲への読み取りと書き込み。Read and write to active selections in the form of text, contiguous cells (matrices), or tables.

  • 表形式のデータ (マトリックスまたはテーブル)。Tabular data (matrices or tables).

  • バインド (Bindings オブジェクトの "add" メソッドで作成)。Bindings (created with the "add" methods of the Bindings object).

  • カスタム XML パーツ (Word の場合のみ)。Custom XML parts (only for Word).

  • ドキュメント上のアドインごとに保持する設定またはアドインの状態。Settings or add-in state persisted per add-in on the document.

また、Document オブジェクトを使用すると、Project ドキュメント内のデータを操作できます。API の Project 固有の機能については、ProjectDocument 抽象クラスのメンバー内に説明文があります。Project 用の作業ウィンドウ アドインの作成の詳細については、「Project 用の作業ウィンドウ アドイン」を参照してください。You can also use the Document object to interact with data in Project documents. The Project-specific functionality of the API is documented in the members ProjectDocument abstract class. For more information about creating task pane add-ins for Project, see Task pane add-ins for Project.

これらのデータ アクセスの形式はすべて、抽象 Document オブジェクトのインスタンスから開始します。All these forms of data access start from an instance of the abstract Document object.

作業ウィンドウ アドインまたはコンテンツ アドインが初期化されると、Context オブジェクトの document プロパティを使用して Document オブジェクトのインスタンスにアクセスできます。Document オブジェクトを使用すると、Word と Excel のドキュメントで共有される共通のデータ アクセス関数を定義でき、Word 文書の CustomXmlParts オブジェクトにもアクセスできます。You can access an instance of the Document object when the task pane or content add-in is initialized by using the document property of the Context object. The Document object defines common data access functions shared across Word and Excel documents, and also provides access to the CustomXmlParts object for Word documents.

Document オブジェクトは、開発者がドキュメント コンテンツにアクセスするための 4 つの方法をサポートしています。The Document object supports four ways for developers to access document contents:

  • 選択範囲ベースのアクセスSelection-based access

  • バインドベースのアクセスBinding-based access

  • カスタム XML パーツベースのアクセス (Word の場合のみ)Custom XML part-based access (Word only)

  • ドキュメント全体へのアクセス (PowerPoint および Word のみ)Entire document-based access (PowerPoint and Word only)

選択範囲ベースおよびバインドベースのデータ アクセス方法のしくみを理解するために、まず、データ アクセス API が、異なる Office アプリケーション間で一貫性のあるデータ アクセスを提供する方法について説明します。To help you understand how selection- and binding-based data access methods work, we will first explain how the data-access APIs provide consistent data access across different Office applications.

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

適用対象: コンテンツ アドインおよび作業ウィンドウ アドインの種類Applies to: Content and task pane add-in types

異なる Office ドキュメント間でシームレスに動作する拡張機能を作成するために、JavaScript API for Office では、共通のデータ型と、異なるドキュメント コンテンツを 3 つの共通のデータ型に強制的に割り当てる機能を通じて、各 Office アプリケーションの特殊性を抽象化します。To create extensions that seamlessly work across different Office documents, the JavaScript API for Office abstracts away the particularities of each Office application through common data types and the ability to coerce different document contents into three common data types.

共通のデータ型Common data types

選択範囲ベースとバインドベースのどちらのデータ アクセスでも、ドキュメント コンテンツは、サポートされているすべての Office アプリケーション間で共通のデータ型を通じて公開されます。Office 2013 では、3 つの主要なデータ型がサポートされています。In both selection-based and binding-based data access, document contents are exposed through data types that are common across all the supported Office applications. In Office 2013, three main data types are supported:

データ型Data type 説明Description ホスト アプリケーションのサポートHost application support
テキストText 選択範囲またはバインド内のデータの文字列表現を提供します。Provides a string representation of the data in the selection or binding. Excel 2013、Project 2013、および PowerPoint 2013 は、プレーンテキストのみがサポートされます。Word 2013 では、3 つのテキスト形式 (プレーン テキスト、HTML、および Office Open XML (OOXML)) がサポートされます。Excel のセル内でテキストが選択されていると (セル内でテキストの一部のみが選択されている場合でも)、選択範囲ベースのメソッドは、セルのコンテンツ全体の読み取りおよび書き込みを行います。Word および PowerPoint でテキストが選択されていると、選択範囲ベースのメソッドは、選択されている文字の並びのみの読み取りおよび書き込みを行います。Project 2013 および PowerPoint 2013 は、選択範囲ベースのデータ アクセスのみをサポートします。In Excel 2013, Project 2013, and PowerPoint 2013, only plain text is supported. In Word 2013, three text formats are supported: plain text, HTML, and Office Open XML (OOXML). When text is selected in a cell in Excel, selection-based methods read and write to the entire contents of the cell, even if only a portion of the text is selected in the cell. When text is selected in Word and PowerPoint, selection-based methods read and write only to the run of characters that are selected. Project 2013 and PowerPoint 2013 support only selection-based data access.
マトリックスMatrix 選択範囲またはバインドに含まれるデータを 2 次元の Array として提供します (JavaScript で配列の配列として実装されているものです)。たとえば、2 つの列にある 2 つ行の string 値は [['a', 'b'], ['c', 'd']] になり、3 つの行を持つ 1 つの列は [['a'], ['b'], ['c']] になります。Provides the data in the selection or binding as a two dimensional Array, which in JavaScript is implemented as an array of arrays. For example, two rows of string values in two columns would be [['a', 'b'], ['c', 'd']], and a single column of three rows would be [['a'], ['b'], ['c']]. マトリックス データ アクセスは Excel 2013 および Word 2013 でのみサポートされています。Matrix data access is supported only in Excel 2013 and Word 2013.
テーブルTable 選択範囲またはバインド内のデータを TableData オブジェクトとして提供します。TableData オブジェクトは、headers プロパティおよび rows プロパティを通じてデータを公開します。Provides the data in the selection or binding as a TableData object. The TableData object exposes the data through the headers and rows properties. テーブル データ アクセスは Excel 2013 および Word 2013 でのみサポートされています。Table data access is supported only in Excel 2013 and Word 2013.

データ型の強制型変換Data type coercion

Document オブジェクトおよび Binding オブジェクトのデータ アクセス メソッドでは、これらのメソッドの coercionType パラメーターおよび対応する CoercionType 列挙値を使用した目的のデータ型の指定をサポートしています。バインドの実際の形状にかかわらず、さまざまな Office アプリケーションでは、要求されるデータ型にデータを強制的に型変換することによって、共通のデータ型をサポートします。たとえば、Word の表または段落が選択されている場合、開発者はそれをプレーン テキスト、HTML、Office Open XML、または表として読み取ることを指定でき、API 実装によって必要な変換やデータ変換が行われます。The data access methods on the Document and Binding objects support specifying the desired data type using the coercionType parameter of these methods, and corresponding CoercionType enumeration values. Regardless of the actual shape of the binding, the different Office applications support the common data types by trying to coerce the data into the requested data type. For example, if a Word table or paragraph is selected, the developer can specify to read it as plain text, HTML, Office Open XML, or a table, and the API implementation handles the necessary transformations and data conversions.

ヒント

どのようなタイミングでデータ アクセスにマトリックスを使用し、どのような場合にテーブルの coercionType を使用するか。 行と列が追加されたときに表形式データが動的に増えるようにし、またテーブル ヘッダーを使用する必要がある場合は、テーブル データ型を使用します (Document または Binding オブジェクト データ アクセス メソッドの coercionType パラメーターに "table" または Office.CoercionType.Table を指定)。データ構造体内での行と列の追加はテーブル データとマトリックス データの両方でサポートされていますが、行と列の追加はテーブル データでのみサポートされています。行と列を追加する予定がなく、データにヘッダー機能が必要ない場合は、マトリックス データ型を使用します (データ アクセス メソッドの coercionType パラメーターに "matrix" または Office.CoercionType.Matrix を指定)。このデータ型では、データとのやり取りについて、より単純なモデルを採用しています。When should you use the matrix versus table coercionType for data access? If you need your tabular data to grow dynamically when rows and columns are added, and you must work with table headers, you should use the table data type (by specifying the coercionType parameter of a Document or Binding object data access method as "table" or Office.CoercionType.Table). Adding rows and columns within the data structure is supported in both table and matrix data, but appending rows and columns is supported only for table data. If you aren't planning on adding rows and columns, and your data doesn't require header functionality, then you should use the matrix data type (by specifying the coercionType parameter of the data access method as "matrix" or Office.CoercionType.Matrix), which provides a simpler model of interacting with the data.

指定された型にデータを強制的に型変換できない場合は、コールバック内の AsyncResult.status プロパティが "failed" を返すため、AsyncResult.error プロパティを使用して Error オブジェクトにアクセスし、メソッド呼び出しが失敗した理由を確認できます。If the data can't be coerced to the specified type, the AsyncResult.status property in the callback returns "failed", and you can use the AsyncResult.error property to access an Error object with information about why the method call failed.

Document オブジェクトによる選択範囲の操作Working with selections using the Document object

Document オブジェクトは、ユーザーの現在の選択を「取得および設定」の方法で読み取りおよび書き込みできるメソッドを公開します。そのために、Document オブジェクトは getSelectedDataAsync メソッドと setSelectedDataAsync メソッドを提供します。The Document object exposes methods that let you to read and write to the user's current selection in a "get and set" fashion. To do that, the Document object provides the getSelectedDataAsync and setSelectedDataAsync methods.

選択範囲に関する操作の実行方法を示すコード例については、「ドキュメントまたはスプレッドシート内のアクティブな選択範囲へのデータの読み取りおよび書き込み」を参照してください。For code examples that demonstrate how to perform tasks with selections, see Read and write data to the active selection in a document or spreadsheet.

Bindings オブジェクトおよび Binding オブジェクトによるバインドの操作Working with bindings using the Bindings and Binding objects

バインドベースのデータ アクセスを使用すると、コンテンツ アドインおよび作業ウィンドウ アドインで、バインドに関連付けられた識別子を介して、ドキュメントまたはスプレッドシートの特定の領域に一貫性のあるアクセスが可能になります。アドインは、最初に、ドキュメントの部分と一意の ID を関連付けるメソッドのいずれか (addFromPromptAsyncaddFromSelectionAsync、または addFromNamedItemAsync) を呼び出すことによって、バインドを確立する必要があります。バインドが確立されると、アドインは提供された ID を使用して、ドキュメントまたはスプレッドシート内の関連付けられた領域に含まれるデータにアクセスできます。バインドを作成すると、アドインには次のようなメリットがあります。Binding-based data access enables content and task pane add-ins to consistently access a particular region of a document or spreadsheet through an identifier associated with a binding. The add-in first needs to establish the binding by calling one of the methods that associates a portion of the document with a unique identifier: addFromPromptAsync, addFromSelectionAsync, or addFromNamedItemAsync. After the binding is established, the add-in can use the provided identifier to access the data contained in the associated region of the document or spreadsheet. Creating bindings provides the following value to your add-in:

  • 表、範囲、またはテキスト (隣接する一連の文字) など、サポートされている Office アプリケーション全体に共通のデータ構造へのアクセスを許可します。Permits access to common data structures across supported Office applications, such as: tables, ranges, or text (a contiguous run of characters).

  • ユーザーによる選択を必要とせずに、読み取り/書き込み操作ができます。Enables read/write operations without requiring the user to make a selection.

  • アドインとドキュメント内のデータの間にリレーションシップが確立されます。バインドはドキュメント内に保持され、後でアクセスできます。Establishes a relationship between the add-in and the data in the document. Bindings are persisted in the document, and can be accessed at a later time.

また、バインドを確立すると、ドキュメントまたはスプレッドシートの特定の領域を範囲とする、データおよび選択範囲の変更イベントをサブスクライブできます。つまり、ドキュメントまたはスプレッドシート全体の全般的な変更ではなく、バインドされた領域内で発生する変更のみがアドインに通知されます。Establishing a binding also allows you to subscribe to data and selection change events that are scoped to that particular region of the document or spreadsheet. This means that the add-in is only notified of changes that happen within the bound region as opposed to general changes across the whole document or spreadsheet.

Bindings オブジェクトが公開している getAllAsync メソッドを使用すると、ドキュメントまたはスプレッドシートで確立されている一連のすべてのバインドにアクセスできます。個々のバインドに ID でアクセスするには、Bindings.getBindingByIdAsync メソッドまたは Office.select メソッドを使用します。Bindings オブジェクトのいずれかのメソッド (addFromSelectionAsyncaddFromPromptAsyncaddFromNamedItemAsync、または releaseByIdAsync) を使用すると、新しいバインドを確立したり既存のバインドを削除したりできます。The Bindings object exposes a getAllAsync method that gives access to the set of all bindings established on the document or spreadsheet. An individual binding can be accessed by its ID using either the Bindings.getBindingByIdAsync or Office.select methods. You can establish new bindings as well as remove existing ones by using one of the following methods of the Bindings object: addFromSelectionAsync, addFromPromptAsync, addFromNamedItemAsync, or releaseByIdAsync.

addFromSelectionAsync メソッド、addFromPromptAsync メソッド、または addFromNamedItemAsync メソッドでバインドを作成する場合、bindingType パラメーターで指定するバインドには 3 つの種類あります。There are three different types of bindings that you specify with the bindingType parameter when you create a binding with the addFromSelectionAsync, addFromPromptAsync or addFromNamedItemAsync methods:

バインドの種類Binding type 説明Description ホスト アプリケーションのサポートHost application support
テキスト バインドText binding テキストとして表現できるドキュメントの領域にバインドします。Binds to a region of the document that can be represented as text. Word では、連続する選択範囲の大部分が有効ですが、Excel では、単一セルの範囲のみがテキスト バインドの対象です。Excel では、プレーン テキストのみがサポートされます。Word では、3 つの形式 (プレーン テキスト、HTML、および Open XML for Office) がサポートされます。In Word, most contiguous selections are valid, while in Excel only single cell selections can be the target of a text binding. In Excel, only plain text is supported. In Word, three formats are supported: plain text, HTML, and Open XML for Office.
マトリックス バインドMatrix binding ヘッダーがない表形式のデータが含まれるドキュメントの固定領域にバインドします。マトリックス バインド内のデータは、2 次元の Array として書き込みまたは読み取りが行われます。JavaScript では、これは、配列の配列として実装されています。たとえば、2 列の string 値が 2 行ある場合は [['a', 'b'], ['c', 'd']] のように書き込みまたは読み取りが行われ、1 列が 3 行ある場合は [['a'], ['b'], ['c']] のように書き込みまたは読み取りが行われます。Binds to a fixed region of a document that contains tabular data without headers. Data in a matrix binding is written or read as a two dimensional Array, which in JavaScript is implemented as an array of arrays. For example, two rows of string values in two columns can be written or read as [['a', 'b'], ['c', 'd']], and a single column of three rows can be written or read as [['a'], ['b'], ['c']]. Excel では、セルの連続する選択範囲を使用してマトリックス バインドを確立できます。Word では、表のみがマトリックス バインドをサポートします。In Excel, any contiguous selection of cells can be used to establish a matrix binding. In Word, only tables support matrix binding.
テーブル バインドTable binding ヘッダーがある表が含まれるドキュメントの領域にバインドします。テーブル バインド内のデータは、TableData オブジェクトとして書き込みまたは読み取りが行われます。TableData オブジェクトは headers および rows プロパティを通じてデータを公開します。Binds to a region of a document that contains a table with headers. Data in a table binding is written or read as a TableData object. The TableData object exposes the data through the headers and rows properties. Excel または Word の表はすべて、テーブル バインドの基礎にできます。テーブル バインドを確立すると、ユーザーが表に追加する新しい各行または各列が、自動的にバインドに含まれます。Any Excel or Word table can be the basis for a table binding. After you establish a table binding, each new row or column a user adds to the table is automatically included in the binding.

Bindings オブジェクトの 3 つの "add" メソッドのいずれかを使用してバインドを作成すると、MatrixBindingTableBinding、または TextBinding のうち対応するオブジェクトのメソッドを使用して、バインドのデータおよびプロパティを操作できます。この 3 つのオブジェクトはすべて、Binding オブジェクトの getDataAsync メソッドおよび setDataAsync メソッドを継承しているので、バインドされたデータを操作できます。After a binding is created by using one of the three "add" methods of the Bindings object, you can work with the binding's data and properties by using the methods of the corresponding object: MatrixBinding, TableBinding, or TextBinding. All three of these objects inherit the getDataAsync and setDataAsync methods of the Binding object that enable to you interact with the bound data.

バインドに関する操作の実行方法を示すコード例については、「ドキュメントまたはスプレッドシート内の領域へのバインド」を参照してください。For code examples that demonstrate how to perform tasks with bindings, see Bind to regions in a document or spreadsheet.

CustomXmlParts オブジェクトおよび CustomXmlPart オブジェクトによるカスタム XML パーツの操作Working with custom XML parts using the CustomXmlParts and CustomXmlPart objects

適用対象: Word の作業ウィンドウ アドインApplies to: Task pane add-ins for Word

API の CustomXmlParts オブジェクトと CustomXmlPart オブジェクトを使用すると、Word 文書内のカスタム XML パーツにアクセスできます。これにより、文書のコンテンツに対する XML 主導の操作が可能になります。The CustomXmlParts and CustomXmlPart objects of the API provide access to custom XML parts in Word documents, which enable XML-driven manipulation of the contents of the document. CustomXmlParts オブジェクトおよび CustomXmlPart オブジェクトとの連携のデモについては、「Word-Add-in-Work-with-custom-XML-parts」のコード例を参照してください。For demonstrations of working with the CustomXmlParts and CustomXmlPart objects, see the Word-add-in-Work-with-custom-XML-parts code sample.

getFileAsync メソッドを使用したドキュメント全体の操作Working with the entire document using the getFileAsync method

適用対象: Word および PowerPoint の作業ウィンドウ アドインApplies to: Task pane add-ins for Word and PowerPoint

Document.getFileAsync メソッド、および File オブジェクトと Slice オブジェクトのメンバーは、一度に最大で 4 MB ずつのスライス (チャンク) に分割して Word および PowerPoint ドキュメント ファイル全体を取得する機能を提供します。詳細については、「PowerPoint または Word 用アドインからドキュメント全体を取得する」を参照してください。The Document.getFileAsync method and members of the File and Slice objects to provide functionality for getting entire Word and PowerPoint document files in slices (chunks) of up to 4 MB at a time. For more information, see Get the whole document from an add-in for PowerPoint or Word.

Mailbox オブジェクトMailbox object

適用対象: Outlook アドインApplies to: Outlook add-ins

Outlook アドインでは、主に Mailbox オブジェクトにより公開されている API のサブセットを使用します。Outlook アドイン専用のオブジェクトおよびメンバー (たとえば、Item オブジェクトなど) にアクセスするには、次のコード行に示すように、Context オブジェクトの mailbox プロパティを使用して、Mailbox オブジェクトにアクセスします。Outlook add-ins primarily use a subset of the API exposed through the Mailbox object. To access the objects and members specifically for use in Outlook add-ins, such as the Item object, you use the mailbox property of the Context object to access the Mailbox object, as shown in the following line of code.

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

さらに、Outlook アドインでは次のオブジェクトを使用できます。Additionally, Outlook add-ins can use the following objects:

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

  • Context オブジェクト: コンテンツおよび表示言語のプロパティへのアクセスに使用します。Context object: for access to content and display language properties.

  • RoamingSettings オブジェクト: アドインがインストールされているユーザーのメールボックスに Outlook アドイン固有のカスタム設定を保存する際に使用します。RoamingSettings object: for saving Outlook add-in-specific custom settings to the user's mailbox where the add-in is installed.

Outlook アドインでの JavaScript の使用については、「Outlook アドイン」を参照してください。For information about using JavaScript in Outlook add-ins, see Outlook add-ins.