ドキュメントやスプレッドシート内のアクティブな選択範囲へのデータの読み取りおよび書き込みRead and write data to the active selection in a document or spreadsheet

Document オブジェクトが公開しているメソッドを使用すると、ユーザーのドキュメントまたはスプレッドシート内の現在の選択範囲への読み取りと書き込みを行うことができます。これは、Document オブジェクトの getSelectedDataAsync メソッドと setSelectedDataAsync メソッドで行います。このトピックでは、ユーザーの選択範囲の読み取り方法、書き込み方法、およびその変更を検出するイベント ハンドラーの作成方法についても説明します。The Document object exposes methods that let you read and write to the user's current selection in a document or spreadsheet. To do that, the Document object provides the getSelectedDataAsync and setSelectedDataAsync methods. This topic also describes how to read, write, and create event handlers to detect changes to the user's selection.

**getSelectedDataAsync** メソッドは、現在のユーザーの選択範囲のみに実行されます。実行中のアドインのセッション間で読み取りおよび書き取りに同じ選択範囲を利用できるように、ドキュメントの選択範囲を保持する必要がある場合、Bindings.addFromSelectionAsync メソッドを使用 (または、Bindings オブジェクトの他の "addFrom" メソッドの 1 つでバインドを作成) して、バインドを追加する必要があります。ドキュメントの領域にバインドを作成して、バインドの読み取りおよび書き込みを行う詳細については、「ドキュメントまたはスプレッドシート内の領域へのバインド」を参照してください。The getSelectedDataAsync method only works against the user's current selection. If you need to persist the selection in the document, so that the same selection is available to read and write across sessions of running your add-in, you must add a binding using the Bindings.addFromSelectionAsync method (or create a binding with one of the other "addFrom" methods of the Bindings object). For information about creating a binding to a region of a document, and then reading and writing to a binding, see Bind to regions in a document or spreadsheet.

選択されたデータを読み取るRead selected data

次の例は、ドキュメント内の選択範囲のデータを getSelectedDataAsync メソッドで取得する方法を示しています。The following example shows how to get data from a selection in a document by 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; 
}

この例では、最初の coercionType パラメーターには Office.CoercionType.Text が指定されています (このパラメーターはリテラル文字列 "text" で指定することもできます)。この場合、コールバック関数の asyncResult パラメーターから取得できる AsyncResult オブジェクトの value プロパティは、ドキュメント内で選択されているテキストを格納している string を返します。別の型変換を指定すると、別の値が取得されます。Office.CoercionType は、使用できる型変換の値を表す列挙型です。Office.CoercionType.Text は文字列 "text" として評価されます。In this example, the first coercionType parameter is specified as Office.CoercionType.Text (you can also specify this parameter by using the literal string "text"). This means that the value property of the AsyncResult object that is available from the asyncResult parameter in the callback function will return a string that contains the selected text in the document. Specifying different coercion types will result in different values. Office.CoercionType is an enumeration of available coercion type values. Office.CoercionType.Text evaluates to the string "text".

ヒント

データ アクセスにおけるマトリックスとテーブルの coercionType の使い分けについて。 行と列が追加されたときに選択済みの表形式データが動的に増えるようにし、またテーブル ヘッダーを使用する必要がある場合は、テーブル データ型を使用します (getSelectedDataAsync メソッドの coercionType パラメーターに "table" または Office.CoercionType.Table を指定)。データ構造体内での行と列の追加はテーブル データとマトリックス データの両方でサポートされていますが、行と列の追加はテーブル データでのみサポートされています。行と列を追加する予定がなく、データにヘッダー機能が必要ない場合は、マトリックス データ型を使用します (getSelecteDataAsync メソッドの coercionType_パラメーターに "matrix" または Office.CoercionType.Matrix を指定)。このデータ型では、データとのやり取りについて、より単純なモデルを採用しています。When should you use the matrix versus table coercionType for data access? If you need your selected 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 the getSelectedDataAsync 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 are 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 getSelecteDataAsync method as "matrix" or Office.CoercionType.Matrix), which provides a simpler model of interacting with the data.

2 番目の callback パラメーターとして関数に渡される匿名関数は、getSelectedDataAsync 操作の完了時に実行されます。この関数は、結果および呼び出しのステータスが格納される asyncResult という 1 つのパラメーターを使用して呼び出されます。呼び出しが失敗した場合は、AsyncResult オブジェクトの error プロパティから Error オブジェクトにアクセスできます。Error.name プロパティと Error.message プロパティの値をチェックして、設定の操作が失敗した理由を判断できます。呼び出しが成功した場合は、ドキュメント内で選択されているテキストが表示されます。The anonymous function that is passed into the function as the second callback parameter is executed when the getSelectedDataAsync operation is completed. The function is called with a single parameter, asyncResult, which contains the result and the status of the call. If the call fails, the error property of the AsyncResult object provides access to the Error object. You can check the value of the Error.name and Error.message properties to determine why the set operation failed. Otherwise, the selected text in the document is displayed.

if ステートメントでは、呼び出しが成功したかどうかの判定に AsyncResult.status プロパティを使用します。Office.AsyncResultStatusAsyncResult.status プロパティが取ることのできる値を表す列挙型です。Office.AsyncResultStatus.Failed は文字列 "failed" として評価されます (こちらもリテラル文字列で指定することもできます)。The AsyncResult.status property is used in the if statement to test whether the call succeeded. Office.AsyncResultStatus is an enumeration of available AsyncResult.status property values. Office.AsyncResultStatus.Failed evaluates to the string "failed" (and, again, can also be specified as that literal string).

選択範囲にデータを書き込むWrite data to the selection

次の例は、"Hello World!" を表示するために選択範囲を設定する方法を示しています。The following example shows how to set the selection to show "Hello World!".

Office.context.document.setSelectedDataAsync("Hello World!", function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write(asyncResult.error.message);
    }
});

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

data パラメーターに異なるオブジェクト型を渡すと、結果が異なります。結果は、ドキュメントで現在選択されているもの、アドインをホストしているアプリケーション、および渡されたデータを現在の選択範囲に型変換できるかどうかによって異なります。Passing in different object types for the data parameter will have different results. The result depends on what is currently selected in the document, which application is hosting your add-in, and whether the data passed in can be coerced to the current selection.

callback パラメーターとして setSelectedDataAsync メソッドに渡される匿名関数は、非同期呼び出しの完了時に実行されます。setSelectedDataAsync メソッドを使用して選択範囲にデータを書き込む場合、コールバックの asyncResult パラメーターは呼び出しのステータスへのアクセスのみを提供し、呼び出しが失敗した場合はError オブジェクトにアクセスします。The anonymous function passed into the setSelectedDataAsync method as the callback parameter is executed when the asynchronous call is completed. When you write data to the selection by using the setSelectedDataAsync method, the asyncResult parameter of the callback provides access only to the status of the call, and to the Error object if the call fails.

注意

Excel 2013 SP1 および Excel Online の関連するビルドのリリースから、現在の選択範囲にテーブルを書き込む際に書式設定ができるようになりました。Starting with the release of the Excel 2013 SP1 and the corresponding build of Excel Online, you can now set formatting when writing a table to the current selection.

選択範囲の変更を検出するDetect changes in the selection

次の例は、Document.addHandlerAsync メソッドを使用して、SelectionChanged イベントのイベント ハンドラーをドキュメント上に追加することで、選択範囲の変更を検出する方法を示しています。The following example shows how to detect changes in the selection by using the Document.addHandlerAsync method to add an event handler for the SelectionChanged event on the document.

Office.context.document.addHandlerAsync("documentSelectionChanged", myHandler, function(result){} 
);

// Event handler function.
function myHandler(eventArgs){
write('Document Selection Changed');
}

// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

最初の eventType パラメーターでは、サブスクライブするイベントの名前を指定しています。文字列 "documentSelectionChanged" をこのパラメーターに指定するのは、 Office.EventType 列挙型のイベントの種類 Office.EventType.DocumentSelectionChanged を渡すことに相当します。The first eventType parameter specifies the name of the event to subscribe to. Passing the string "documentSelectionChanged" for this parameter is equivalent to passing the Office.EventType.DocumentSelectionChanged event type of the Office.EventType enumeration.

2 番目の handler パラメーターとして関数に渡される myHander() 関数は、ドキュメントで選択範囲が変更されたときに実行されるイベント ハンドラーです。この関数は、非同期処理の完了時に、DocumentSelectionChangedEventArgs オブジェクトへの参照が格納される eventArgs という 1 つのパラメーターを使用して呼び出されます。DocumentSelectionChangedEventArgs.document プロパティを使用すると、このイベントが発生したドキュメントにアクセスできます。The myHander() function that is passed into the function as the second handler parameter is an event handler that is executed when the selection is changed on the document. The function is called with a single parameter, eventArgs, which will contain a reference to a DocumentSelectionChangedEventArgs object when the asynchronous operation completes. You can use the DocumentSelectionChangedEventArgs.document property to access the document that raised the event.

注意

addHandlerAsync メソッドを再び呼び出して、handler パラメーターに追加のイベント ハンドラー関数を指定すると、特定のイベントに複数のイベント ハンドラーを追加できます。この場合、各イベント ハンドラー関数の名前は一意である必要があります。You can add multiple event handlers for a given event by calling the addHandlerAsync method again and passing in an additional event handler function for the handler parameter. This will work correctly as long as the name of each event handler function is unique.

選択範囲の変更の検出を中止するStop detecting changes in the selection

次の例は、document.removeHandlerAsync メソッドを呼び出して、Document.SelectionChanged イベントのリッスンを中止する方法を示しています。The following example shows how to stop listening to the Document.SelectionChanged event by calling the document.removeHandlerAsync method.

Office.context.document.removeHandlerAsync("documentSelectionChanged", {handler:myHandler}, function(result){});

2 番目の handler パラメーターとして渡される myHandler 関数名は、SelectionChanged イベントから削除されるイベント ハンドラーを指定します。The myHandler function name that is passed as the second handler parameter specifies the event handler that will be removed from the SelectionChanged event.

重要

removeHandlerAsync メソッドを呼び出すときにオプションの handler パラメーターを省略すると、指定された eventType のすべてのイベント ハンドラーが削除されます。If the optional handler parameter is omitted when the removeHandlerAsync method is called, all event handlers for the specified eventType will be removed.