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

アドインが Excel ブックまたは Word ドキュメントの特定の領域への信頼性の高いアクセスを必要とする場合は、バインドを使用します。 バインドによって領域は一意の ID に関連付けられ、ユーザーが選択を変更したり、ドキュメントを再度開いた後でアドインがその領域に戻ることができます。

バインドを使用すると、アドインは次のことができます。

• テーブル、範囲、テキストなどの一般的なデータ構造にアクセスします。
• ユーザーが最初にリージョンを選択せずに、データの読み取りと書き込みを行います。
• バインド領域内のデータと選択の変更を監視します。
• バインドがドキュメントと共に保存されるので、セッション間で関係を維持します。

適切なバインドの種類を選択する

Office では、 3 種類の制インドがサポートされています。 リージョンと、アドインで読み取りまたは書き込みを行う必要があるデータに基づいて種類を選択します。

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

テキスト バインド

テキスト バインドは、ドキュメント領域をテキストとして表します。

Word では、ほとんどの連続した選択が機能します。 Excel では、テキスト バインドを使用できるのは、1 つのセル選択のみです。 Excel ではプレーン テキストのみがサポートされていますが、Word ではプレーン テキスト、HTML、Open XML for Office の 3 つの形式がサポートされています。

マトリックス バインド

マトリックス バインディングは、ヘッダーのない表形式データの固定領域を表します。

行列データを 2 次元 Array (JavaScript の配列) として読み書きします。 たとえば、2 つの列にある 2 行の string 値は [['a', 'b'], ['c', 'd']] のように見え、3 行の 1 つの列は [['a'], ['b'], ['c']] のように表示されます。

Excel では、連続したセルの選択によってマトリックス バインドが有効になります。 Word では、表のみがマトリックス バインドをサポートします。

テーブル バインド

テーブル バインディングは、ヘッダー付きのテーブルを表します。

テーブル バインディングのデータは、 TableData オブジェクトとして読み書きされます。 TableData オブジェクトは、headers プロパティと rows プロパティを通じてデータを公開します。

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

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

現在の選択範囲からバインドを作成する

次の例では、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 を指定しない場合は、ID が自動的に生成されます。

最後の コールバック パラメーターとして渡された匿名関数は、バインドの作成が完了したときに実行されます。 この関数は、呼び出しのステータスを持つ AsyncResult オブジェクトへのアクセスを提供する 1 つのパラメーター 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 を指定しない場合は、ID が自動的に生成されます。

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

次のスクリーンショットは、Excel の組み込みの範囲選択プロンプトを示しています。

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

次の関数は、addFromNamedItemAsync メソッドを使用して、既存の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"、2 番目のテーブルに "Table2" というように名前を割り当てます。 Excel UI のテーブルにわかりやすい名前を割り当てるには、[テーブル ツール] の [テーブル名 ] プロパティを使用します |[デザイン ] タブ。

次の関数は、列 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 値が割り当てられていません。 Word UI にわかりやすい名前を割り当てるには、[開発] タブの [コントロール] グループからリッチ テキスト コンテンツ コントロールを挿入した後、[コントロール] グループの [プロパティ] コマンドを使用して、[コンテンツ コントロールのプロパティ] ダイアログを表示します。 次に、コンテンツ コントロールの Title プロパティを、コードから参照する名前に設定します。

次の関数は、"FirstName" という名前のリッチ テキスト コンテンツ コントロールにWordテキスト バインドを作成し、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;
}

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

次の例では、 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 パラメーターとして渡された匿名関数は、操作が完了したときに実行されます。 この関数は、ドキュメント内のバインドの配列を含む 1 つのパラメーター asyncResult で呼び出されます。 配列は反復処理されて、バインドの ID を含む文字列が作成されます。 この文字列がメッセージ ボックスに表示されます。

getByIdAsync を使用して ID によるバインドを取得する

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

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" のバインドを含む 1 つのパラメーター asyncResult を使用して呼び出されます。

を使用して ID でバインドを取得する Office.select

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

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 プロパティと getByIdAsync メソッドを使用して Binding オブジェクトを取得します。

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 番目のパラメーターとして渡される匿名関数は、操作が完了したときに実行されるコールバックです。 この関数は、呼び出しのステータスを含む 1 つのパラメーター 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 イベントにイベント ハンドラーを関連付けることによって、バインド内の選択範囲の変更を検出できます。 これを行うには、addHandlerAsync の eventType パラメーターを Office.EventType.BindingSelectionChanged または "bindingSelectionChanged" として指定します。

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

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

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

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

関連項目

• Office JavaScript API について
• Office アドインにおける非同期プログラミング
• ドキュメントまたはスプレッドシート内のアクティブな選択範囲へのデータの読み取りおよび書き込み