ドキュメントやスプレッドシート内のアクティブな選択範囲へのデータの読み取りおよび書き込み

Document オブジェクトが公開しているメソッドを使用すると、ユーザーのドキュメントまたはスプレッドシート内の現在の選択範囲への読み取りと書き込みを行うことができます。 これを行うために、 Document オブジェクトは、 getSelectedDataAsync メソッドと setSelectedDataAsync メソッドを提供します。 このトピックでは、ユーザーの選択範囲の読み取り方法、書き込み方法、およびその変更を検出するイベント ハンドラーの作成方法についても説明します。

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" に評価されます。

メソッドに 2 番目のパラメーターコールバックとして渡される匿名関数は、getSelectedDataAsync操作が完了したときに実行されます。 この関数は、結果および呼び出しのステータスが格納される asyncResult という 1 つのパラメーターを使用して呼び出されます。 呼び出しが失敗した場合、AsyncResult オブジェクトの error プロパティから 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イベント型を渡すことと同じです。

メソッドに 2 番目のパラメーター handler として渡される myHandler() 関数 は、ドキュメントで選択内容が変更されたときに実行されるイベント ハンドラーです。 この関数は、非同期処理の完了時に、 DocumentSelectionChangedEventArgs オブジェクトへの参照が格納される eventArgs という 1 つのパラメーターを使用して呼び出されます。 DocumentSelectionChangedEventArgs.document プロパティを使用すると、このイベントが発生したドキュメントにアクセスできます。

選択範囲の変更の検出を中止する

次の例は、document.removeHandlerAsync メソッドを呼び出して、Document.SelectionChanged イベントのリッスンを中止する方法を示しています。

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

2 番目のパラメーター handler として渡されるmyHandler関数名は、SelectionChanged イベントから削除されるイベント ハンドラーを指定します。