Office 2013 でのコンテンツ アドインと作業ウィンドウ アドインの Office JavaScript API のサポートOffice JavaScript API support for content and task pane add-ins in Office 2013

Office JavaScript API を使用して、Office 2013 ホスト アプリケーションの作業ウィンドウやコンテンツ用のアドインを作成できます。コンテンツと作業ウィンドウのアドインをサポートするオブジェクトとメソッドは、次のように分類されます。You can use the Office JavaScript API to create task pane or content add-ins for Office 2013 host applications. The objects and methods that content and task pane add-ins support are categorized as follows:

  1. 他の Office アドインと共有する共通のオブジェクト。 これらのオブジェクトには、OfficeContext、および AsyncResult があります。Office オブジェクトは Office JavaScript API のルート オブジェクトです。Context オブジェクトはアドインのランタイム環境を表します。OfficeContext は、いずれも Office アドインの基礎となるオブジェクトです。AsyncResult オブジェクトは、ユーザーが文書内で選択したものを読み取る getSelectedDataAsync メソッドに返されたデータなどの非同期操作の結果を表します。Common objects shared with other Office Add-ins. These objects include Office, Context, and AsyncResult. The Office object is the root object of the Office JavaScript API. The Context object represents the add-in's runtime environment. Both Office and Context are the fundamental objects for any Office Add-in. The AsyncResult object represents the results of an asynchronous operation, such as the data returned to the getSelectedDataAsync method, which reads what a user has selected in a document.

  2. The Document object. The majority of the API available to content and task pane add-ins is exposed through the methods, properties, and events of the Document object. A content or task pane add-in can use the Office.context.document property to access the Document object, and through it, can access the key members of the API for working with data in documents, such as the Bindings and CustomXmlParts objects, and the getSelectedDataAsync, setSelectedDataAsync, and getFileAsync methods. The Document object also provides the mode property for determining whether a document is read-only or in edit mode, the url property to get the URL of the current document, and access to the Settings object. The Document object also supports adding event handlers for the SelectionChanged event, so you can detect when a user changes their selection in the document.The Document object. The majority of the API available to content and task pane add-ins is exposed through the methods, properties, and events of the Document object. A content or task pane add-in can use the Office.context.document property to access the Document object, and through it, can access the key members of the API for working with data in documents, such as the Bindings and CustomXmlParts objects, and the getSelectedDataAsync, setSelectedDataAsync, and getFileAsync methods. The Document object also provides the mode property for determining whether a document is read-only or in edit mode, the url property to get the URL of the current document, and access to the Settings object. The Document object also supports adding event handlers for the SelectionChanged event, so you can detect when a user changes their selection in the document.

    コンテンツ アドインや作業ウィンドウ アドインが Document オブジェクトにアクセスできるのは、DOM とランタイム環境が Office.initialize イベント用のイベント ハンドラーなどで読み込まれた後だけです。アドインが初期化されるときのイベント フローと、DOM とラインタイムが正常に読み込まれたかどうかの確認方法については、「DOM とランタイム環境の読み込み」を参照してください。A content or task pane add-in can access the Document object only after the DOM and runtime environment has been loaded, typically in the event handler for the Office.initialize event. For information about the flow of events when an add-in is initialized, and how to check that the DOM and runtime and loaded successfully, see Loading the DOM and runtime environment.

  3. 特定の機能を操作するためのオブジェクト。 API の特定の機能を操作するには、次のオブジェクトとメソッドを使用します。Objects for working with specific features. To work with specific features of the API, use the following objects and methods:

    • Bindings オブジェクトのメソッドを使用して、バインドを作成または取得します。また、Binding オブジェクトのメソッドとプロパティを使用して、データを操作します。The methods of the Bindings object to create or get bindings, and the methods and properties of the Binding object to work with data.

    • CustomXmlPartsCustomXmlPart、および関連するオブジェクトを使用して、Word 文書内のカスタム XML パーツを作成および操作します。The CustomXmlParts, CustomXmlPart and associated objects to create and manipulate custom XML parts in Word documents.

    • File オブジェクトと Slice オブジェクトを使用して、文書全体のコピーを作成し、それをチャンクまたは「スライス」に分割してから、それらのスライスに含まれるデータを読み取りまたは転送します。The File and Slice objects to create a copy of the entire document, break it into chunks or "slices", and then read or transmit the data in those slices.

    • Settings オブジェクトを使用して、ユーザー設定やアドインの状態などのカスタム データを保存します。The Settings object to save custom data, such as user preferences, and add-in state.

重要

API メンバーの一部は、コンテンツ アドインと作業ウィンドウ アドインをホスト可能なすべての Office アプリケーションでサポートされているわけではありません。サポートされているメンバーを特定するには、次のいずれかを参照してください。Some of the API members aren't supported across all Office applications that can host content and task pane add-ins. To determine which members are supported, see any of the following:

Office ホスト アプリケーション全体にわたる Office JavaScript API サポートの概要については、「JavaScript API for Office について」を参照してください。For a summary of Office JavaScript API support across Office host applications, see Understanding the JavaScript API for Office.

アクティブな選択範囲の読み取りと書き込みReading and writing to an active selection

文書、スプレッドシート、またはプレゼンテーション内のユーザーの現在の選択範囲に対して読み書きをすることができます。アドイン用のホスト アプリケーションに応じて、Document オブジェクトの getSelectedDataAsync メソッドと setSelectedDataAsync メソッド内のパラメーターとして読み書きするデータ構造のタイプを指定できます。たとえば、Word には任意のデータ タイプ (テキスト、HTML、表形式データ、または Office Open XML)、Excel にはテキストと表形式データ、および PowerPoint と Project にはテキストを指定できます。ユーザーの選択範囲に対する変更を検出するためのイベント ハンドラーを作成することもできます。以下の例では、getSelectedDataAsync メソッドを使用して、選択範囲からデータをテキストとして取得します。You can read or write to the user's current selection in a document, spreadsheet, or presentation. Depending on the host application for your add-in, you can specify the type of data structure to read or write as a parameter in the getSelectedDataAsync and setSelectedDataAsync methods of the Document object. For example, you can specify any type of data (text, HTML, tabular data, or Office Open XML) for Word, text and tabular data for Excel, and text for PowerPoint and Project. You can also create event handlers to detect changes to the user's selection. The following example gets data from the selection as text using the getSelectedDataAsync method.

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; 
}

詳細と例については、「ドキュメントやスプレッドシート内のアクティブな選択範囲へのデータの読み取りおよび書き込み」を参照してください。For more details and examples, see Read and write data to the active selection in a document or spreadsheet.

文書またはスプレッドシート内の領域へのバインドBinding to a region in a document or spreadsheet

getSelectedDataAsync メソッドと setSelectedDataAsync メソッドを使用して、文書、スプレッドシート、またはプレゼンテーション内のユーザーの現在の選択範囲を読み取りまたは書き込みできます。ただし、ユーザーに選択を要求せずにアドインの複数の実行セッションに渡って文書内の同じ領域にアクセスする場合は、最初にその領域をバインドする必要があります。そのバインドした領域に対するデータおよび選択範囲変更イベントにサブスクライブすることもできます。You can use the getSelectedDataAsync and setSelectedDataAsync methods to read or write to the user's current selection in a document, spreadsheet, or presentation. However, if you would like to access the same region in a document across sessions of running your add-in without requiring the user to make a selection, you should first bind to that region. You can also subscribe to data and selection change events for that bound region.

バインドは、Bindings オブジェクトの addFromNamedItemAsync メソッド、addFromPromptAsync メソッド、または addFromSelectionAsync メソッドを使用して追加できます。これらのメソッドは、バインド内のデータにアクセスするため、あるいは、データ変更または選択範囲変更イベントにサブスクライブするために使用可能な識別子を返します。You can add a binding by using addFromNamedItemAsync, addFromPromptAsync, or addFromSelectionAsync methods of the Bindings object. These methods return an identifier that you can use to access data in the binding, or to subscribe to its data change or selection change events.

Bindings.addFromSelectionAsync メソッドを使用して、文書内で現在選択されているテキストにバインドを追加する例を次に示します。The following is an example that adds a binding to the currently selected text in a document, by using the Bindings.addFromSelectionAsync method.

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; 
}

詳細と例については、「ドキュメントまたはスプレッドシート内の領域へのバインド」を参照してください。For more details and examples, see Bind to regions in a document or spreadsheet.

文書全体の取得Getting entire documents

作業ウィンドウ アドインが PowerPoint または Word で実行される場合は、Document.getFileAsync メソッド、File.getSliceAsync メソッド、および File.closeAsync メソッドを使用して、プレゼンテーションまたは文書全体を取得できます。If your task pane add-in runs in PowerPoint or Word, you can use the Document.getFileAsync, File.getSliceAsync, and File.closeAsync methods to get an entire presentation or document.

Document.getFileAsync を呼び出すと、File オブジェクトに文書のコピーが返されます。File オブジェクトは、Slice オブジェクトとして表現される「チャンク」内の文書へのアクセスを提供します。getFileAsync を呼び出すときに、ファイル タイプ (テキストまたは圧縮 Open Office XML 形式) とスライスのサイズ (4 MB 以下) を指定できます。File オブジェクトの内容にアクセスするには、Slice.data プロパティに生データを返す File.getSliceAsync を呼び出します。圧縮形式を指定した場合は、ファイル データがバイト配列で返されます。ファイルを Web サービスに転送する場合は、圧縮生データを base64 エンコード文字列に変換してから送信できます。最後に、ファイルのスライスの取得が完了したら、File.closeAsync メソッドを使用して文書を閉じます。When you call Document.getFileAsync, you get a copy of the document in a File object. The File object provides access to the document in "chunks" represented as Slice objects. When you call getFileAsync, you can specify the file type (text or compressed Open Office XML format), and size of the slices (up to 4MB). To access the contents of the File object, you then call File.getSliceAsync which returns the raw data in the Slice.data property. If you specified compressed format, you will get the file data as a byte array. If you are transmitting the file to a web service, you can transform the compressed raw data to a base64-encoded string before submission. Finally, when you are finished getting slices of the file, use the File.closeAsync method to close the document.

詳細については、PowerPoint や Word 用のアドインからドキュメント全体を取得する方法を参照してください。For more details, see how to get the whole document from an add-in for PowerPoint or Word.

Word 文書のカスタム XML パーツの読み取りと書き込みReading and writing custom XML parts of a Word document

Open Office XML ファイル形式とコンテンツ コントロールを使用すれば、Word 文書にカスタム XML パーツを追加して、その文書内のコンテンツ コントロールに XML パーツ内の要素をバインドすることができます。文書を開くと、Word がバインドされたコンテンツ コントロールを読み取り、カスタム XML パーツからのデータを自動的に設定します。ユーザーは、コンテンツ コントロールにデータを書き込むこともできます。ユーザーが文書を保存すると、コントロール内のデータがバインドされた XML パーツに保存されます。Word 用の作業ウィンドウ アドインは、Document.customXmlParts プロパティ、CustomXmlParts オブジェクト、CustomXmlPart オブジェクト、および CustomXmlNode オブジェクトを使用して、文書に対して動的にデータを読み書きすることができます。Using the Open Office XML file format and content controls, you can add custom XML parts to a Word document and bind elements in the XML parts to content controls in that document. When you open the document, Word reads and automatically populates bound content controls with data from the custom XML parts. Users can also write data into the content controls, and when the user saves the document, the data in the controls will be saved to the bound XML parts. Task pane add-ins for Word, can use the Document.customXmlParts property,CustomXmlParts, CustomXmlPart, and CustomXmlNode objects to read and write data dynamically to the document.

カスタム XML パーツは名前空間に関連付けることができます。名前空間内のカスタム XML パーツからデータを取得するには、CustomXmlParts.getByNamespaceAsync メソッドを使用します。Custom XML parts may be associated with namespaces. To get data from custom XML parts in a namespace, use the CustomXmlParts.getByNamespaceAsync method.

CustomXmlParts.getByIdAsync メソッドを使用して、GUID でカスタム XML パーツにアクセスすることもできます。カスタム XML パーツを取得したら、CustomXmlPart.getXmlAsync メソッドを使用して XML データを取得します。You can also use the CustomXmlParts.getByIdAsync method to access custom XML parts by their GUIDs. After getting a custom XML part, use the CustomXmlPart.getXmlAsync method to get the XML data.

文書に新しいカスタム XML パーツを追加するには、Document.customXmlParts プロパティを使用して文書内に存在するカスタム XML パーツを取得し、CustomXmlParts.addAsync メソッドを呼び出します。To add a new custom XML part to a document, use the Document.customXmlParts property to get the custom XML parts that are in the document, and call the CustomXmlParts.addAsync method.

作業ウィンドウ アドインでのカスタム XML パーツの操作方法の詳細については、「Office Open XML を使用してより良い Word 用アドインを作成する」を参照してください。For detailed information about how to work with custom XML parts with a task pane add-in, see Creating Better Add-ins for Word with Office Open XML.

アドイン設定を保存するPersisting add-in settings

多くの場合、ユーザー設定やアドインの状態など、アドインのカスタム データを保存し、次回、アドインを開いたとき、そのデータにアクセスする必要があります。一般的な Web プログラミング手法を利用し、ブラウザーの Cookie や HTML 5 Web ストレージなど、そのデータを保存できます。あるいは、アドインを Excel、PowerPoint、Word で実行する場合、Settings オブジェクトのメソッドを使用できます。Settings オブジェクトで作成したデータは、アドインを挿入して保存したスプレッドシート、プレゼンテーション、文書に保存されます。このデータは、それを作成したアドインでのみ利用できます。Often you need to save custom data for your add-in, such as a user's preferences or the add-in's state, and access that data the next time the add-in is opened. You can use common web programming techniques to save that data, such as browser cookies or HTML 5 web storage. Alternatively, if your add-in runs in Excel, PowerPoint, or Word, you can use the methods of the Settings object. Data created with the Settings object is stored in the spreadsheet, presentation, or document that the add-in was inserted into and saved with. This data is available to only the add-in that created it.

To avoid roundtrips to the server where the document is stored, data created with the Settings object is managed in memory at run time. Previously saved settings data is loaded into memory when the add-in is initialized, and changes to that data are only saved back to the document when you call the Settings.saveAsync method. Internally, the data is stored in a serialized JSON object as name/value pairs. You use the get, set, and remove methods of the Settings object, to read, write, and delete items from the in-memory copy of the data. The following line of code shows how to create a setting named themeColor and set its value to 'green'.To avoid roundtrips to the server where the document is stored, data created with the Settings object is managed in memory at run time. Previously saved settings data is loaded into memory when the add-in is initialized, and changes to that data are only saved back to the document when you call the Settings.saveAsync method. Internally, the data is stored in a serialized JSON object as name/value pairs. You use the get, set, and remove methods of the Settings object, to read, write, and delete items from the in-memory copy of the data. The following line of code shows how to create a setting named themeColor and set its value to 'green'.

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

set メソッドと remove メソッドを使用した設定データの作成または削除はそのデータのメモリ内コピーに対して機能するため、saveAsync を呼び出して、設定データに対する変更をアドインが操作する文書内に保持する必要があります。Because settings data created or deleted with the set and remove methods is acting on an in-memory copy of the data, you must call saveAsync to persist changes to settings data into the document your add-in is working with.

Settings オブジェクトのメソッドを使用したカスタム データの操作方法の詳細については、「アドインの状態および設定を保持する」を参照してください。For more details about working with custom data using the methods of the Settings object, see Persisting add-in state and settings.

プロジェクト文書のプロパティの読み取りReading properties of a project document

作業ウィンドウ アドインが Project で動作する場合は、そのアドインでアクティブ プロジェクト内のプロジェクト フィールド、リソース、およびタスク フィールドの一部からデータを読み取ることができます。これを実現するには、追加の Project 固有の機能を提供するように Document オブジェクトを拡張する ProjectDocument オブジェクトのメソッドとイベントを使用します。If your task pane add-in runs in Project, your add-in can read data from some of the project fields, resource, and task fields in the active project. To do that, you use the methods and events of the ProjectDocument object, which extends the Document object to provide additional Project-specific functionality.

Project データの読み取りの例については、「テキスト エディターを使用して Project 2013 用の作業ウィンドウ アドインを初めて作成する」を参照してください。For examples of reading Project data, see Create your first task pane add-in for Project 2013 by using a text editor.

アクセス許可モデルとガバナンスPermissions model and governance

アドインは、そのマニフェスト内の Permissions 要素を使用して、必要な機能のレベルにアクセスするためのアクセス許可を Office JavaScript API に要求します。たとえば、アドインで文書に対する読み取りと書き込みアクセス権が必要な場合は、そのマニフェストで ReadWriteDocument をその Permissions 要素内のテキスト値として指定する必要があります。アクセス許可はユーザーのプライバシーとセキュリティを保護するために存在しているので、ベスト プラクティスとしては、その機能に必要な最低限のアクセス許可を要求することをお勧めします。次の例は、作業ウィンドウのマニフェストで ReadDocument アクセス許可を要求する方法を示しています。Your add-in uses the Permissions element in its manifest to request permission to access the level of functionality it requires from the Office JavaScript API. For example, if your add-in requires read/write access to the document, its manifest must specify ReadWriteDocument as the text value in its Permissions element. Because permissions exist to protect a user's privacy and security, as a best practice you should request the minimum level of permissions it needs for its features. The following example shows how to request the ReadDocument permission in a task pane's manifest.

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

詳細については、「コンテンツ アドインおよび作業ウィンドウ アドインでの API 使用のアクセス許可を要求する」を参照してください。For more information, see Requesting permissions for API use in content and task pane add-ins.

関連項目See also