绑定到文档或电子表格中的区域

项目
04/07/2023

基于绑定的数据访问使内容和任务窗格加载项能够通过与绑定相关联的标识符一致地访问文档或电子表格的特定区域。加载项首先需要通过调用将文档的某一部分与唯一标识符相关联的以下某个方法来建立绑定：addFromPromptAsync、addFromSelectionAsync 或 addFromNamedItemAsync。建立绑定后，加载项可以使用提供的标识符访问文档或电子表格的关联区域中包含的数据。创建绑定可为加载项提供以下值。

允许访问跨支持的 Office 应用程序的通用数据结构，例如：表、区域或文本（一系列连续字符）。
允许读/写操作，而不需要用户做出选择。
在加载项和文档中的数据之间建立关系。绑定会保留在文档中，以后可以进行访问。

建立绑定还允许您订阅仅限文档或电子表格的特定区域的数据和选择更改事件。这意味着，加载项只会收到绑定区域内发生的更改的通知，而不是收到整个文档或电子表格内的常规更改的通知。

Bindings 对象公开 getAllAsync 方法，通过该方法可以访问在文档或电子表格中建立的所有绑定的集合。可以使用任一绑定通过 ID 访问单个绑定。getByIdAsync 方法或 Office.select 函数。可使用 Bindings 对象的以下方法之一建立新绑定和删除现有绑定：addFromSelectionAsync、addFromPromptAsync、addFromNamedItemAsync 或 releaseByIdAsync。

绑定类型

使用 addFromSelectionAsync、addFromPromptAsync 或 addFromNamedItemAsync 方法创建绑定时，可以使用 bindingType 参数指定三种不同类型的绑定。

文本绑定 - 绑定到可表示为文本的文档区域。

在 Word 中，大多数连续选区都是有效的，而在 Excel 中，只有单个单元格选区才能作为文本绑定的目标。在 Excel 中，只支持纯文本。在 Word 中，支持以下三种格式：纯文本、HTML 和 Open XML for Office。
矩阵绑定 - 绑定到文档的固定区域，其中包含不带标题的表格数据。矩阵绑定中的数据以二维数组的形式写入或读取，在 JavaScript 中，二维数组作为数组实现。例如，两行两列 string 值可以写入或读取为 [['a', 'b'], ['c', 'd']]，而三行单列则可以写入或读取为 [['a'], ['b'], ['c']]。

在 Excel 中，任何连续选择的单元格都可用于建立矩阵绑定。在 Word 中，只有表格支持矩阵绑定。
表绑定 - 绑定到包含带标题的表的文档区域。表绑定中的数据以 TableData 对象的形式写入或读取。对象 TableData 通过 headers 和 rows 属性公开数据。

任何 Excel 或 Word 表格均可作为表格绑定的基础。建立表格绑定后，用户添加到表格中的每个新行或新列都自动包含在绑定中。

使用对象的三个“addFrom”方法 Bindings 之一创建绑定后，可以使用相应对象的方法处理绑定的数据和属性： MatrixBinding、 TableBinding 或 TextBinding。这三个对象全部继承对象的 getDataAsync 和 Binding 方法，使你能够与绑定的数据交互。

注意

您应该何时使用矩阵和表格绑定？ 当使用的表格数据包含一个总计行时，如果外接程序的脚本需要访问总计行中的值，或检测用户的选区是否在总计行中，则必须使用矩阵绑定。如果为包含总计行的表格数据建立了表格绑定，那么 TableBinding.rowCount 属性和事件处理程序中 rowCount 对象的 startRow 和属性将不会在值中反映总计行。要解决此限制，必须建立矩阵绑定以使用总计行。

向用户当前所选内容中添加绑定

以下示例演示如何使用 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 是可用的绑定类型值的枚举。

第二个可选参数是一个对象，它指定要创建的新绑定的 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。

第二个参数是一个对象，它包含创建的新绑定的 ID。如果不指定 ID，则会自动生成一个。

在绑定创建完成后，将执行作为第三个回调参数传入方法的匿名函数。执行回调函数时， AsyncResult 对象包含调用的状态和新创建的绑定。

图 1 显示 Excel 中内置的范围选择提示。

图 1. Excel 选择数据 UI

“选择数据”对话框。

向已命名项目添加绑定

以下示例演示如何使用 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，addFromNamedItemAsyncitemName 方法的参数可以引用现有的命名区域、使用A1引用样式 ("A1:A3")指定的区域或表。默认情况下，在 Excel 中添加表会为你添加的第一个表分配名称“Table1”，为你添加的第二个表分配名称“Table2”，以此类推。若要在 Excel UI 中为表分配有意义的名称，请使用表Table Name工具 | 上的属性功能区的“设计”选项卡。

注意

在 Excel 中，将表格指定为命名项目时，必须完全限定名称，以将工作表名称包含在表格名称中，格式如下： "Sheet1!Table1"

以下示例在 Excel 中创建一个绑定到列 A ( "A1:A3") 的前三个单元格，分配 ID "MyCities"，然后将三个城市名称写入该绑定。

 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，addFromNamedItemAsyncitemName 方法的参数引用Title内容控件的 Rich Text 属性。 (不能绑定到内容控件以外的 Rich Text 内容控件。)

默认情况下，内容控件未 Title*分配任何值。若要在 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。

在操作完成时，将作为第二个回调参数传递到方法的匿名函数执行。该函数用单个参数 asyncResult 来调用，其中包含调用状态和 ID 为"myBinding"的绑定。

使用 Office 对象的 select 函数按 ID 获取绑定

以下示例演示如何使用 Office.select 函数通过在选择器字符串中指定绑定对象承诺的 ID 来获取文档中的 Binding 对象承诺。然后，它会调用 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。如果 promise 无法返回 Binding 对象，则 onError 回调可用于访问 asyncResult.error 对象以获取详细信息。如果需要调用 Binding 对象的成员，而不是函数返回select的 Binding 对象承诺公开的四个方法，请改用 Document.bindings 属性和 Bindings 来使用 getByIdAsync 方法。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。

作为第二个参数传递到方法的匿名函数是在操作完成时执行的回调。函数是使用单个参数 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。不同绑定类型接受不同类型的数据。

传入方法的匿名函数是在操作完成时执行的回调。使用包含结果状态的单个参数 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”。

dataChanged作为第二个处理程序参数传递到方法中的函数是当绑定中的数据发生更改时执行的事件处理程序。该函数用单个参数 eventArgs 来调用，其中包含对绑定的引用。此绑定可用来检索更新的数据。

类似地，你可以通过向绑定的 SelectionChanged 事件附加事件处理程序来检测用户是否更改绑定中的选择。为此，请将 eventType 方法的参数指定为 Office.EventType.BindingSelectionChanged 或 "bindingSelectionChanged"。

可以为给定事件添加多个事件处理程序，方法是再次调用 addHandlerAsync 方法，并为 handler 参数传入一个其他事件处理程序函数。只要每个事件处理程序函数的名称保持唯一，此方法就有用。

删除事件处理程序

若要删除事件的事件处理程序，请调用 removeHandlerAsync 方法将事件类型作为第一个 eventType 参数传入，将要删除的事件处理程序函数的名称作为第二个 handler 参数传入。例如，以下函数将删除在上一节的示例中添加的 dataChanged 事件处理程序函数。

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

重要

如果在调用 removeHandlerAsync 方法时省略可选的 handler 参数，则将删除指定 eventType 的所有事件处理程序。

通过