ドキュメントやスプレッドシート内の領域へのバインド

[アーティクル]
04/07/2023

バインドベースのデータアクセスにより、コンテンツアドインおよび作業ウィンドウアドインは、ドキュメントまたはスプレッドシートの特定の領域に ID を通じて一貫性をもってアクセスできます。アドインは、最初に、ドキュメントの部分と一意の ID を関連付けるいずれかのメソッド (addFromPromptAsync、addFromSelectionAsync、または addFromNamedItemAsync) を呼び出すことによって、バインドを確立する必要があります。バインドが確立されると、アドインは提供された ID を使用して、ドキュメントまたはスプレッドシート内の関連付けられた領域に含まれるデータにアクセスできます。バインドを作成すると、アドインに次の値が提供されます。

表、範囲、またはテキスト (隣接する一連の文字) など、サポートされている Office アプリケーション全体に共通のデータ構造へのアクセスを許可します。
ユーザーによる選択を必要とせずに、読み取り/書き込み操作ができます。
アドインとドキュメント内のデータの間にリレーションシップが確立されます。バインドはドキュメント内に保持され、後でアクセスできます。

また、バインドを確立すると、ドキュメントまたはスプレッドシートの特定の領域を範囲とする、データおよび選択範囲の変更イベントをサブスクライブできます。つまり、ドキュメントまたはスプレッドシート全体の全般的な変更ではなく、バインドされた領域内で発生する変更のみがアドインに通知されます。

Bindings オブジェクトが公開している getAllAsync メソッドを使用すると、ドキュメントまたはスプレッドシートで確立されている一連のすべてのバインドにアクセスできます。個々のバインドには、いずれかのバインディングを使用してその ID でアクセスできます。getByIdAsync メソッドまたは Office.select 関数。 Bindings オブジェクトの addFromSelectionAsync、addFromPromptAsync、addFromNamedItemAsync、または releaseByIdAsync メソッドのいずれかを使用して、新しいバインドを設定したり、既存のバインドを削除したりできます。

バインドの種類

addFromSelectionAsync、addFromPromptAsync メソッド、または addFromNamedItemAsync メソッドを使用してバインドを作成するときに、bindingType パラメーターで指定するバインドには 3 種類あります。

テキストバインド - テキスト として表すことができるドキュメントの領域にバインドします。

Word では、連続する選択範囲の大部分が有効ですが、Excel では、単一セルの範囲のみがテキストバインドの対象です。 Excel では、プレーンテキストのみがサポートされます。 Word では、3 つの形式 (プレーンテキスト、HTML、および Open XML for Office) がサポートされます。
マトリックスバインド - ヘッダーのない表形式データを含むドキュメントの固定領域にバインドします。マトリックスバインド内のデータは、2 次元配列として書き込まれるか、読み取られます。JavaScript では配列の配列として実装されます。たとえば、2 つの列の 2 行の 文字列 値を [['a', 'b'], ['c', 'd']]として書き込みまたは読み取ることができ、3 行の 1 つの列を [['a'], ['b'], ['c']]として書き込んだり読み取ったりできます。

Excel では、セルの連続する選択範囲を使用してマトリックスバインドを確立できます。 Word では、表のみがマトリックスバインドをサポートします。
テーブルバインド - ヘッダーを含むテーブルを含むドキュメントの領域にバインドします。テーブルバインド内のデータは、 TableData オブジェクトとして書き込まれるか、読み取られます。 TableData オブジェクトは、headers プロパティと rows プロパティを介してデータを公開します。

Excel または Word の表はすべて、テーブルバインドの基礎にできます。テーブルバインドを確立すると、ユーザーが表に追加する新しい各行または各列が、自動的にバインドに含まれます。

Bindings オブジェクトの 3 つの "addFrom" メソッドのいずれかを使用してバインドを作成した後は、対応するオブジェクトの MatrixBinding、TableBinding、または TextBinding のメソッドを使用して、バインドのデータとプロパティを操作できます。この 3 つのオブジェクトはすべて、オブジェクトの getDataAsync メソッドおよび Binding メソッドを継承しているので、バインドされたデータを操作できます。

注:

マトリックスとテーブルのバインドを使用する必要がある場合 操作している表形式データに合計行が含まれている場合は、アドインのスクリプトが合計行の値にアクセスする必要がある場合、またはユーザーの選択が合計行に含まれていることを検出する必要がある場合は、マトリックスバインドを使用する必要があります。合計行を含む表形式データのテーブルバインドを確立した場合、TableBinding.rowCount プロパティと、イベントハンドラーの BindingSelectionChangedEventArgs オブジェクトの rowCount プロパティと startRow プロパティは、値の合計行を反映しません。 To work around this limitation, you must use establish a matrix binding to work with the total row.

ユーザーの現在の選択範囲にバインドを追加する

次の例では、addFromSelectionAsync メソッドを使用して、myBindingというテキストバインドをドキュメント内の現在の選択範囲に追加する方法を示します。

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

この例では、指定したバインドの種類はテキストです。つまり、選択範囲に対して TextBinding が作成されます。バインドが備えているデータと操作はバインドの種類ごとに異なります。 Office.BindingType は、使用できるバインドの種類の値を示す列挙型です。

2 番目のオプションのパラメーターは、作成している新しいバインドの ID を指定するオブジェクトです。指定しない場合、ID は自動的に生成されます。

バインドの作成が完了すると、最後の コールバック パラメーターとしてメソッドに渡される匿名関数が実行されます。この関数の単一のパラメーター asyncResult を通じて、呼び出しの状態を示す AsyncResult オブジェクトにアクセスできます。 AsyncResult.value プロパティには、新規作成するバインドとして指定した種類の Binding オブジェクトへの参照が格納されます。この Binding オブジェクトを使用して、データを取得および設定できます。

プロンプトからバインドを追加する

次の例では、addFromPromptAsync メソッドを使用して、myBinding というテキストバインドを追加する方法を示します。このメソッドでは、ユーザーはアプリケーションの組み込み範囲選択プロンプトを使用してバインドの範囲を指定できます。

function bindFromPrompt() {
    Office.context.document.bindings.addFromPromptAsync(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;
}

この例では、指定されているバインドの種類はテキストです。つまり、ユーザーがプロンプトで指定した選択範囲に対して TextBinding が作成されます。

2 番目のパラメーターは、作成している新しいバインドの ID を含むオブジェクトです。指定しない場合、ID は自動的に生成されます。

バインディングの作成が完了すると、3 番目の コールバック パラメーターとしてメソッドに渡される匿名関数が実行されます。コールバック関数が実行されると、AsyncResult オブジェクトには呼び出しのステータスおよび新しく作成されたバインドが格納されます。

図 1 は、Excel の組み込み範囲選択プロンプトを示しています。

図 1. Excel のデータ選択 UI

[データの選択] ダイアログ。

名前付きアイテムにバインドを追加する

次の例では、addFromNamedItemAsync メソッドを使用して、item という名前の既存のmyRangeにバインドを "マトリックス" バインドとして追加し、バインドのidを "myMatrix" として割り当てる方法を示します。

function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync("myRange", "matrix", {id:'myMatrix'}, function (result) {
        if (result.status == 'succeeded'){
            write('Added new binding with type: ' + result.value.type + ' and id: ' + result.value.id);
            }
        else
            write('Error: ' + result.error.message);
    });
}

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

Excel の場合、addFromNamedItemAsync メソッドの itemName パラメーターは、既存の名前付き範囲、A1参照スタイル ("A1:A3")で指定された範囲、またはテーブルを参照できます。既定では、Excel のテーブルを追加すると、最初に追加したテーブルには "Table1"、次に追加したテーブルには "Table2" という名前が割り当てられます。 Excel UI でテーブルにわかりやすい名前を割り当てるには Table Name 、 Table Tools | リボンの [デザイン] タブ。

注:

Excel では、名前付き項目としてテーブルを指定する場合は、次の形式でテーブルの名前にワークシート名を含めるために、名前を完全に修飾する必要があります。 "Sheet1!Table1"

次の例では、列 A ( "A1:A3") の最初の 3 つのセルにバインドを Excel で作成し、id "MyCities"を割り当ててから、そのバインドに 3 つの市区町村名を書き込みます。

 function bindingFromA1Range() {
    Office.context.document.bindings.addFromNamedItemAsync("A1:A3", "matrix", {id: "MyCities" },
        function (asyncResult) {
            if (asyncResult.status == "failed") {
                write('Error: ' + asyncResult.error.message);
            }
            else {
                // Write data to the new binding.
                Office.select("bindings#MyCities").setDataAsync([['Berlin'], ['Munich'], ['Duisburg']], { coercionType: "matrix" },
                    function (asyncResult) {
                        if (asyncResult.status == "failed") {
                            write('Error: ' + asyncResult.error.message);
                        }
                    });
            }
        });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

Word の場合、addFromNamedItemAsync メソッドの itemName パラメーターは、Rich Text コンテンツコントロールの Title プロパティを参照します。 (Rich Text コンテンツコントロール以外のコンテンツコントロールにはバインドできません)。

既定では、コンテンツコントロールには Title*value が割り当てされていません。 Word UI で意味のあるテーブル名を割り当てるには、リボンの [ 開発者] タブの [ コントロール] グループから [ リッチテキスト] コンテンツコントロールを挿入した後、[ コントロール] グループの [ プロパティ] コマンドを使用して [ コンテンツコントロールのプロパティ] ダイアログボックスを表示します。次に、コンテンツコントロールの Title プロパティを、コードから参照する名前に設定します。

次の例では、word で "FirstName" という名前のリッチテキストコンテンツコントロールへのテキストバインドを作成し、 id"firstName" を割り当ててから、その情報を表示します。

function bindContentControl() {
    Office.context.document.bindings.addFromNamedItemAsync('FirstName', 
        Office.BindingType.Text, {id:'firstName'},
        function (result) {
            if (result.status === Office.AsyncResultStatus.Succeeded) {
                write('Control bound. Binding.id: '
                    + result.value.id + ' Binding.type: ' + result.value.type);
            } else {
                write('Error:', result.error.message);
            }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

すべてのバインドを取得する

次の例は、Bindings.getAllAsync メソッドを使用して、ドキュメント内のすべてのバインドを取得する方法を示しています。

Office.context.document.bindings.getAllAsync(function (asyncResult) {
    let bindingString = '';
    for (let i in asyncResult.value) {
        bindingString += asyncResult.value[i].id + '\n';
    }
    write('Existing bindings: ' + bindingString);
});

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

callback パラメーターとしてメソッドに渡される匿名関数は、操作の完了時に実行されます。関数は、ドキュメント内のバインドの配列を含む単一のパラメーター asyncResultで呼び出されます。配列は反復処理されて、バインドの ID を含む文字列が作成されます。この文字列がメッセージボックスに表示されます。

Bindings オブジェクトの getByIdAsync メソッドを使用して ID でバインドを取得する

次の例は、getByIdAsync メソッドを使用し、ID を指定してドキュメント内のバインドを取得する方法を示しています。この例では、前述のメソッドのいずれかを使用して 'myBinding' という名前のバインドがドキュメントに追加されたと想定しています。

Office.context.document.bindings.getByIdAsync('myBinding', function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        write('Retrieved 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; 
}

この例では、最初の id パラメーターは取得するバインドの ID です。

2 番目の コールバック パラメーターとしてメソッドに渡される匿名関数は、操作の完了時に実行されます。この関数は、呼び出しのステータスおよび ID が "myBinding" であるバインドが格納される asyncResult という 1 つのパラメーターを使用して呼び出されます。

Office オブジェクトの select 関数を使用して ID によるバインドを取得する

次の例は、 Office.select 関数を使用して、セレクター文字列でその ID を指定して、ドキュメント内の Binding オブジェクトの promise を取得する方法を示しています。その後、Binding.getDataAsync メソッドを呼び出して、指定したバインドからデータを取得します。この例では、前述のメソッドのいずれかを使用して 'myBinding' という名前のバインドがドキュメントに追加されたと想定しています。

Office.select("bindings#myBinding", function onError(){}).getDataAsync(function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write(asyncResult.value);
    }
});

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

注:

select関数 promise が Binding オブジェクトを正常に返した場合、そのオブジェクトは getDataAsync、setDataAsync、addHandlerAsync、removeHandlerAsync の 4 つのメソッドのみを公開します。 promise が Binding オブジェクトを返すことができない場合は、 onError コールバックを使用して asyncResult.error オブジェクトにアクセスして詳細を取得できます。 select関数によって返される Binding オブジェクト promise によって公開される 4 つのメソッド以外の Binding オブジェクトのメンバーを呼び出す必要がある場合は、代わりに Document.bindings プロパティと Bindings を使用して getByIdAsync メソッドを使用します。binding オブジェクトを取得する getByIdAsync メソッド。

ID でバインドを解除する

次の例は、releaseByIdAsync メソッドを使用して ID を指定し、ドキュメント内のバインドを解除する方法を示しています。

Office.context.document.bindings.releaseByIdAsync('myBinding', function (asyncResult) {
    write('Released myBinding!');
});

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

この例で、最初の id パラメーターは解除するバインドの ID です。

2 番目のパラメーターとしてメソッドに渡される匿名関数は、操作が完了したときに実行されるコールバックです。関数は、呼び出しの状態を含む単一のパラメーター asyncResult で呼び出されます。

バインドからデータを読み取る

次の例は、getDataAsync メソッドを使用して既存のバインドからデータを取得する方法を示しています。

myBinding.getDataAsync(function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    } else {
        write(asyncResult.value);
    }
});

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

myBinding は、ドキュメント内の既存のテキストバインドを格納している変数です。代わりに、Office.select メソッドを使用して ID によってバインドにアクセスし、次のように getDataAsync メソッドの呼び出しを開始できます。

Office.select("bindings#myBindingID").getDataAsync

メソッドに渡される匿名関数は、操作が完了したときに実行されるコールバックです。 AsyncResult.value プロパティには、myBinding 内のデータが格納されます。その値の型は、バインドの種類により異なります。この例のバインドはテキストバインドです。そのため、値には文字列が格納されます。マトリックスバインドおよびテーブルバインドを使用して作業する追加の例については、getDataAsync メソッドのトピックを参照してください。

バインドにデータを書き込む

次の例は、setDataAsync メソッドを使用して既存のバインドにデータを設定する方法を示しています。

myBinding.setDataAsync('Hello World!', function (asyncResult) { });

myBinding は、ドキュメント内の既存のテキストバインドを格納している変数です。

この例では、最初のパラメーターは、 myBindingに設定する値です。これはテキストバインドのため、値は string です。バインドの種類が異なる場合、異なる型のデータが使用されます。

メソッドに渡される匿名関数は、操作が完了したときに実行されるコールバックです。関数は、結果の状態を含む 1 つのパラメーター asyncResultで呼び出されます。

バインド内のデータまたは選択範囲の変更を検出する

次の例は、ID が "MyBinding" であるバインドの DataChanged イベントにイベントハンドラーを関連付ける方法を示しています。

function addHandler() {
Office.select("bindings#MyBinding").addHandlerAsync(
    Office.EventType.BindingDataChanged, dataChanged);
}
function dataChanged(eventArgs) {
    write('Bound data changed in binding: ' + eventArgs.binding.id);
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message;
}

myBinding は、ドキュメント内の既存のテキストバインドを格納している変数です。

addHandlerAsync メソッドの最初の eventType パラメーターは、サブスクライブするイベントの名前を指定します。 Office.EventType は、使用できるイベントの種類の値の列挙型です。 Office.EventType.BindingDataChanged は文字列 "bindingDataChanged" に評価されます。

2 番目のハンドラー パラメーターとしてメソッドに渡されるdataChanged関数は、バインド内のデータが変更されたときに実行されるイベントハンドラーです。この関数は、バインドへの参照が格納される eventArgs という 1 つのパラメーターを使用して呼び出されます。このバインドを使用して、更新されたデータを取得できます。

同様に、バインドの SelectionChanged イベントにイベントハンドラーを関連付けることによって、バインド内の選択範囲の変更を検出できます。これを行うには、eventType メソッドのパラメーターを Office.EventType.BindingSelectionChanged または "bindingSelectionChanged" と指定します。

addHandlerAsync メソッドを再び呼び出して、handler パラメーターに追加のイベントハンドラー関数を指定すると、特定のイベントに複数のイベントハンドラーを追加できます。この場合、各イベントハンドラー関数の名前は一意である必要があります。

イベントハンドラーを削除する

イベントのイベントハンドラーを削除するには、最初の eventType パラメーターにイベントの種類を指定し、2 番目の handler パラメーターに削除するイベントハンドラー関数の名前を指定して、removeHandlerAsync メソッドを呼び出します。たとえば、次の例では、前のセクションの例で追加した dataChanged イベントハンドラー関数が削除されます。

function removeEventHandlerFromBinding() {
    Office.select("bindings#MyBinding").removeHandlerAsync(
        Office.EventType.BindingDataChanged, {handler:dataChanged});
}

重要

removeHandlerAsync メソッドの呼び出し時に省略可能な handler パラメーターを省略すると、指定したeventTypeのすべてのイベントハンドラーが削除されます。

次の方法で共有

ドキュメントやスプレッドシート内の領域へのバインド

バインドの種類

ユーザーの現在の選択範囲にバインドを追加する

プロンプトからバインドを追加する

名前付きアイテムにバインドを追加する

すべてのバインドを取得する

Bindings オブジェクトの getByIdAsync メソッドを使用して ID でバインドを取得する

Office オブジェクトの select 関数を使用して ID によるバインドを取得する

ID でバインドを解除する

バインドからデータを読み取る

バインドにデータを書き込む

バインド内のデータまたは選択範囲の変更を検出する

イベントハンドラーを削除する

関連項目

その他のリソース

次の方法で共有

ドキュメントやスプレッドシート内の領域へのバインド

バインドの種類

ユーザーの現在の選択範囲にバインドを追加する

プロンプトからバインドを追加する

名前付きアイテムにバインドを追加する

すべてのバインドを取得する

Bindings オブジェクトの getByIdAsync メソッドを使用して ID でバインドを取得する

Office オブジェクトの select 関数を使用して ID によるバインドを取得する

ID でバインドを解除する

バインドからデータを読み取る

バインドにデータを書き込む

バインド内のデータまたは選択範囲の変更を検出する

イベント ハンドラーを削除する

関連項目

その他のリソース

イベントハンドラーを削除する