ドキュメントやスプレッドシート内のアクティブな選択範囲へのデータの読み取りおよび書き込み
Document オブジェクトが公開しているメソッドを使用すると、ユーザーのドキュメントまたはスプレッドシート内の現在の選択範囲への読み取りと書き込みを行うことができます。 これを行うために、 オブジェクトには Document メソッドと setSelectedDataAsync メソッドがgetSelectedDataAsync用意されています。 このトピックでは、ユーザーの選択範囲の読み取り方法、書き込み方法、およびその変更を検出するイベント ハンドラーの作成方法についても説明します。
メソッドは getSelectedDataAsync 、ユーザーの現在の選択に対してのみ機能します。 実行中のアドインのセッション間で読み取りおよび書き取りに同じ選択範囲を利用できるように、ドキュメントの選択範囲を保持する必要がある場合、Bindings.addFromSelectionAsync メソッドを使用 (または、Bindings オブジェクトの他の "addFrom" メソッドの 1 つでバインドを作成) して、バインドを追加する必要があります。 ドキュメントの領域にバインドを作成して、バインドの読み取りおよび書き込みを行う詳細については、「ドキュメントまたはスプレッドシート内の領域へのバインド」を参照してください。
選択されたデータを読み取る
次の例は、ドキュメント内の選択範囲のデータを getSelectedDataAsync メソッドで取得する方法を示しています。
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" に評価されます。
ヒント
データ アクセスにマトリックスを使用する場合と、テーブルの coercionType を使用する場合。 行と列を追加するときに、選択した表形式データを動的に拡張する必要があり、テーブル ヘッダーを操作する必要がある場合は、テーブル データ型を使用する必要があります (または として "table"Office.CoercionType.Tableメソッドの coercionType パラメーターをgetSelectedDataAsync指定します)。 データ構造内の行と列の追加は、テーブルとマトリックス データの両方でサポートされますが、行と列の追加はテーブル データでのみサポートされます。 行と列の追加を計画していない場合、データにヘッダー機能が必要ない場合は、マトリックス データ型 (メソッドの getSelectedDataAsynccoercionType パラメーターを または Office.CoercionType.Matrixとして"matrix"指定) を使用する必要があります。これにより、データと対話するモデルが簡単になります。
2 番目のパラメーター コールバックとして メソッドに渡される匿名関数は、操作の完了時に getSelectedDataAsync 実行されます。 この関数は、結果および呼び出しのステータスが格納される asyncResult という 1 つのパラメーターを使用して呼び出されます。 呼び出しが失敗した場合、オブジェクトの AsyncResulterror プロパティは Error オブジェクトへのアクセスを提供します。 Error.name プロパティと Error.message プロパティの値をチェックして、設定の操作が失敗した理由を判断できます。 呼び出しが成功した場合は、ドキュメント内で選択されているテキストが表示されます。
The AsyncResult.status property is used in the if statement to test whether the call succeeded. Office.AsyncResultStatus は、使用可能 AsyncResult.status なプロパティ値の列挙です。 Office.AsyncResultStatus.Failed は"failed" という文字列に評価されます (また、リテラル文字列として指定することもできます)。
選択範囲にデータを書き込む
次の例は、"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;
}
データ パラメーターに対して異なるオブジェクト型を渡すと、結果が異なります。 結果は、ドキュメントで現在選択されている内容、アドインをホストしている Office クライアント アプリケーション、および渡されたデータを現在の選択範囲に強制できるかどうかによって異なります。
The anonymous function passed into the setSelectedDataAsync method as the callback parameter is executed when the asynchronous call is completed. メソッドを使用 setSelectedDataAsync して選択範囲にデータを書き込む場合、コールバックの asyncResult パラメーターは、呼び出しの状態と、呼び出しが失敗した場合は Error オブジェクトへのアクセスのみを提供します。
選択範囲の変更を検出する
次の例は、Document.addHandlerAsync メソッドを使用して、SelectionChanged イベントのイベント ハンドラーをドキュメント上に追加することで、選択範囲の変更を検出する方法を示しています。
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と同じです。
myHandler()メソッドに 2 番目のパラメーター handler として渡される関数は、ドキュメントで選択範囲が変更されたときに実行されるイベント ハンドラーです。 この関数は、非同期処理の完了時に、 DocumentSelectionChangedEventArgs オブジェクトへの参照が格納される eventArgs という 1 つのパラメーターを使用して呼び出されます。 DocumentSelectionChangedEventArgs.document プロパティを使用すると、このイベントが発生したドキュメントにアクセスできます。
注:
メソッドをもう一度呼び出し、handler パラメーターの追加のイベント ハンドラー関数をaddHandlerAsync渡すことで、特定のイベントに対して複数のイベント ハンドラーを追加できます。 この場合、各イベント ハンドラー関数の名前は一意である必要があります。
選択範囲の変更の検出を中止する
次の例は、document.removeHandlerAsync メソッドを呼び出して、Document.SelectionChanged イベントのリッスンを中止する方法を示しています。
Office.context.document.removeHandlerAsync("documentSelectionChanged", {handler:myHandler}, function(result){});
2 番目のパラメーター handler として渡される関数名はmyHandler、イベントから削除されるイベント ハンドラーをSelectionChanged指定します。
重要
メソッドの呼び出し時に省略可能な handler パラメーターを removeHandlerAsync 省略すると、指定した eventType のすべてのイベント ハンドラーが削除されます。
Office Add-ins