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

Document.getSelectedDataAsyncとDocument.setSelectedDataAsyncを使用して、ユーザーの現在の選択を読み書きする方法について説明します。 たとえば、コールバック ベースのスニペットと最新の Promise/非同期ラッパーが含まれているため、async/await を使用できます。

• これを使用する場合: ユーザーの選択 (クリップボードに似た)、軽量な操作、または即時の UI 更新に対する一時的な編集を簡単に行うことができます。 セッション間で永続化が必要な場合は、バインドを使用します。
• 適用対象: Wordと Excel (ホストによって動作が異なります。後でホストノートを参照してください)。 Web とデスクトップの違いについては、サポートされているプラットフォームでテストします。
• キー API: Office.context.document.getSelectedDataAsync、 Office.context.document.setSelectedDataAsync、 Office.EventType.DocumentSelectionChanged。

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) {
        // Failure handling: Show the error message in the UI.
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        // Success: `asyncResult.value` contains the selected text.
        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" に評価されます。

予期される出力: 選択したテキストを id messageで page 要素に書き込みます。

メソッドに 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) {
        // Show the error message if the call fails.
        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 オブジェクトにのみアクセスできます。

予想される出力: ドキュメント内の現在の選択は、"Hello World!" というテキストに置き換えられます。(選択範囲とホストでテキストの挿入がサポートされている場合)。

Modern Promise/async ラッパー

async/await を使用する場合は、コールバック API の周囲に小さな Promise ラッパーを使用します。 ラッパーの例:

function getSelectedDataAsyncWithPromise(coercionType) {
    return new Promise((resolve, reject) => {
        Office.context.document.getSelectedDataAsync(coercionType, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) reject(result.error);
            else resolve(result.value);
        });
    });
}

function setSelectedDataAsyncWithPromise(data) {
    return new Promise((resolve, reject) => {
        Office.context.document.setSelectedDataAsync(data, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) reject(result.error);
            else resolve();
        });
    });
}

// Usage with async/await.
async function example() {
    try {
        const text = await getSelectedDataAsyncWithPromise(Office.CoercionType.Text);
        console.log('Selected:', text);
        await setSelectedDataAsyncWithPromise(text + ' (processed)');
    } catch (err) {
        console.error(err.message || err);
    }
}

詳細については、「 Promise を返す関数で共通 API をラップする」を参照してください。

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

次の例は、Document.addHandlerAsync メソッドを使用して、SelectionChanged イベントのイベント ハンドラーをドキュメント上に追加することで、選択範囲の変更を検出する方法を示しています。

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

// Event handler function.
function myHandler(eventArgs){
    // `eventArgs` contains a `document` reference when available.
    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 プロパティを使用すると、このイベントが発生したドキュメントにアクセスできます。

ホスト アプリケーションノート: Excel では、多くの場合、選択変更イベントはブック範囲に関するイベントです (マトリックスまたはテーブル強制型を使用します)。 Wordでは、選択イベントはテキストまたはコンテンツにフォーカスされます。 アドインでサポートされているホスト内のイベント ハンドラーをテストします。

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

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

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

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

トラブルシューティング

• 空の選択: ユーザーに選択がない場合は何も返されません。 コンテンツの選択をユーザーに確認して求めるメッセージを表示します。
• 強制不一致: 予想されるデータに適切な coercionType (text、 matrix、 table、 html) を使用します。
• ホストの制限: 一部のホストでは、特定の強制が許可されない場合があります。 詳細については、「 Office.CoercionType 」を参照してください。
• アクセス許可: アドインのマニフェストに、使用する API に適切なアクセス許可があることを確認します。

次の手順

セッション間の永続的なデータについては、「 ドキュメントまたはスプレッドシート内のリージョンにバインドする」を参照してください。 その他の便利なトピック: 認証、 ランタイム、 アプリケーション固有の例。