Office.Binding interface

表示对文档部分的绑定。

Binding 对象公开所有绑定所拥有的功能,而不管类型如何。

从不直接调用 Binding 对象。 它是对象的抽象父类,表示每种类型的绑定: Office.MatrixBindingOffice.TableBindingOffice.TextBinding。 这三个对象都从 Binding 对象继承 getDataAsync 和 setDataAsync 方法,这些方法使你能够与绑定中的数据进行交互。 它们还继承用于查询这些属性值的 ID 和类型属性。 此外,MatrixBinding 和 TableBinding 对象揭示特定于矩阵和表的功能的其他方法,如对行和列计数。

注解

应用程序:Word,Excel (已弃用,改用 Excel.Binding)

要求集

属性

document

获取与绑定关联的 Document 对象。

id

在同一 Office.Document 对象中的绑定之间唯一标识此绑定的字符串。

type

获取绑定的类型。

方法

addHandlerAsync(eventType, handler, options, callback)

将事件处理程序添加到指定 Office.EventType 的 对象。 支持的 EventType 为 Office.EventType.BindingDataChangedOffice.EventType.BindingSelectionChanged

addHandlerAsync(eventType, handler, callback)

将事件处理程序添加到指定 Office.EventType 的 对象。 支持的 EventType 为 Office.EventType.BindingDataChangedOffice.EventType.BindingSelectionChanged

getDataAsync(options, callback)

返回绑定中包含的数据。

getDataAsync(callback)

返回绑定中包含的数据。

removeHandlerAsync(eventType, options, callback)

从绑定移除指定事件类型的指定处理程序。

removeHandlerAsync(eventType, callback)

从绑定移除指定事件类型的指定处理程序。

setDataAsync(data, options, callback)

将数据写入指定的绑定对象表示的文档的绑定部分。

setDataAsync(data, callback)

将数据写入指定的绑定对象表示的文档的绑定部分。

属性详细信息

document

获取与绑定关联的 Document 对象。

document: Office.Document;

属性值

示例

Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
    write(asyncResult.value.document.url);
});

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

id

在同一 Office.Document 对象中的绑定之间唯一标识此绑定的字符串。

id: string;

属性值

string

示例

Office.context.document.bindings.getByIdAsync("myBinding", function (asyncResult) {
    write(asyncResult.value.id);
});

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

type

获取绑定的类型。

type: Office.BindingType;

属性值

示例

Office.context.document.bindings.getByIdAsync("MyBinding", function (asyncResult) { 
    write(asyncResult.value.type); 
}) 

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

方法详细信息

addHandlerAsync(eventType, handler, options, callback)

将事件处理程序添加到指定 Office.EventType 的 对象。 支持的 EventType 为 Office.EventType.BindingDataChangedOffice.EventType.BindingSelectionChanged

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: Office.AsyncResult<void>) => void): void;

参数

eventType
Office.EventType

事件类型。 对于绑定,它可以是 Office.EventType.BindingDataChangedOffice.EventType.BindingSelectionChanged

handler

any

要添加的事件处理程序函数,其唯一的参数类型为 Office.BindingDataChangedEventArgsOffice.BindingSelectionChangedEventArgs

options
Office.AsyncContextOptions

提供一个选项,用于保留任何类型的上下文数据(不变),以便在回调中使用。

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResult

返回

void

注解

要求集BindingEvents

只要每个事件处理程序函数的名称唯一,就可以为指定的 eventType 添加多个事件处理程序。

addHandlerAsync(eventType, handler, callback)

将事件处理程序添加到指定 Office.EventType 的 对象。 支持的 EventType 为 Office.EventType.BindingDataChangedOffice.EventType.BindingSelectionChanged

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: Office.AsyncResult<void>) => void): void;

参数

eventType
Office.EventType

事件类型。 对于绑定,它可以是 Office.EventType.BindingDataChangedOffice.EventType.BindingSelectionChanged

handler

any

要添加的事件处理程序函数,其唯一的参数类型为 Office.BindingDataChangedEventArgsOffice.BindingSelectionChangedEventArgs

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResult

返回

void

注解

要求集BindingEvents

只要每个事件处理程序函数的名称唯一,就可以为指定的 eventType 添加多个事件处理程序。

示例

// The following code sample calls the select function of the Office object to access the binding
// with ID "MyBinding", and then calls the addHandlerAsync method to add a handler function 
// for the bindingDataChanged event of that binding.
function addEventHandlerToBinding() {
    Office.select("bindings#MyBinding").addHandlerAsync(
        Office.EventType.BindingDataChanged, onBindingDataChanged);
}

function onBindingDataChanged(eventArgs) {
    write("Data has 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; 
}
// To add an event handler for the BindingSelectionChanged event of a binding, 
// use the addHandlerAsync method of the Binding object.
// The event handler receives an argument of type BindingSelectionChangedEventArgs.
function addEventHandlerToBinding() {
    Office.select("bindings#MyBinding").addHandlerAsync(
        Office.EventType.BindingSelectionChanged, onBindingSelectionChanged);
}

function onBindingSelectionChanged(eventArgs) {
    write(eventArgs.binding.id + " has been selected.");
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

getDataAsync(options, callback)

返回绑定中包含的数据。

getDataAsync<T>(options?: GetBindingDataOptions, callback?: (result: AsyncResult<T>) => void): void;

参数

options
Office.GetBindingDataOptions

提供有关如何获取绑定中的数据的选项。

callback

(result: Office.AsyncResult<T>) => void

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResultvalue结果的 属性是指定绑定中的值。 coercionType如果 (指定参数,并且调用成功) ,则数据将采用 CoercionType 枚举主题中所述的格式返回。

返回

void

注解

要求集

从 MatrixBinding 或 TableBinding 调用时,如果 (指定了可选的 startRow、startColumn、rowCount 和 columnCount 参数,并且它们指定了连续且有效的范围) ,则 getDataAsync 方法将返回绑定值的子集。

getDataAsync(callback)

返回绑定中包含的数据。

getDataAsync<T>(callback?: (result: AsyncResult<T>) => void): void;

参数

callback

(result: Office.AsyncResult<T>) => void

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResultvalue结果的 属性是指定绑定中的值。 coercionType如果 (指定参数,并且调用成功) ,则数据将采用 CoercionType 枚举主题中所述的格式返回。

返回

void

注解

要求集

从 MatrixBinding 或 TableBinding 调用时,如果 (指定了可选的 startRow、startColumn、rowCount 和 columnCount 参数,并且它们指定了连续且有效的范围) ,则 getDataAsync 方法将返回绑定值的子集。

示例

function showBindingData() {
    Office.select("bindings#MyBinding").getDataAsync(function (asyncResult) {
        write(asyncResult.value)
    });
}

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

// There is an important difference in behavior between using the "table" and "matrix" coercionType with the
// Binding.getDataAsync method, with respect to data formatted with header rows, as shown in the following
// two examples. These code examples show event handler functions for the Binding.SelectionChanged event.

// If you specify the "table" coercionType, the TableData.rows property ( result.value.rows in the following
// code example) returns an array that contains only the body rows of the table. So, its 0th row will be the
// first non-header row in the table.
function selectionChanged(evtArgs) { 
    Office.select("bindings#TableTranslate").getDataAsync(
        { coercionType: 'table', 
          startRow: evtArgs.startRow, 
          startCol: 0, 
          rowCount: 1, 
          columnCount: 1 },  
        function (result) { 
            if (result.status == 'succeeded') { 
                write("Image to find: " + result.value.rows[0][0]); 
            } 
            else 
                write(result.error.message); 
    }); 
}     
// Function that writes to a div with id='message' on the page. 
function write(message){ 
    document.getElementById('message').innerText += message; 
}

// However, if you specify the "matrix" coercionType, result.value in the following code example returns an array
// that contains the table header in the 0th row. If the table header contains multiple rows, then these are all
// included in the result.value matrix as separate rows before the table body rows are included.
function selectionChanged(evtArgs) { 
    Office.select("bindings#TableTranslate").getDataAsync(
        { coercionType: 'matrix', 
          startRow: evtArgs.startRow, 
          startCol: 0, 
          rowCount: 1, 
          columnCount: 1 },  
        function (result) { 
            if (result.status == 'succeeded') { 
                write("Image to find: " + result.value[1][0]); 
            } 
            else 
                write(result.error.message); 
    }); 
}     
// Function that writes to a div with id='message' on the page. 
function write(message){ 
    document.getElementById('message').innerText += message; 
}

removeHandlerAsync(eventType, options, callback)

从绑定移除指定事件类型的指定处理程序。

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

参数

eventType
Office.EventType

事件类型。 对于绑定,它可以是 Office.EventType.BindingDataChangedOffice.EventType.BindingSelectionChanged

options
Office.RemoveHandlerOptions

提供用于确定删除哪些事件处理程序的选项。

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResult

返回

void

注解

要求集BindingEvents

removeHandlerAsync(eventType, callback)

从绑定移除指定事件类型的指定处理程序。

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

参数

eventType
Office.EventType

事件类型。 对于绑定,它可以是 Office.EventType.BindingDataChangedOffice.EventType.BindingSelectionChanged

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResult

返回

void

注解

要求集BindingEvents

示例

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

setDataAsync(data, options, callback)

将数据写入指定的绑定对象表示的文档的绑定部分。

setDataAsync(data: TableData | any, options?: SetBindingDataOptions, callback?: (result: AsyncResult<void>) => void): void;

参数

data

Office.TableData | any

当前选择中要设置的数据。 按 Office 应用程序分类的可能数据类型:

字符串:在 Windows 上Excel web 版和,仅在 Web 上和 Windows 上Word

数组数组:仅限 Excel 和 Word

Office.TableData:仅限 Excel 和 Word

HTML:仅在 Web 和 Windows 上Word

Office Open XML:仅限Word

options
Office.SetBindingDataOptions

提供有关如何在绑定中设置数据的选项。

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResult

返回

void

注解

要求集

为数据传递的值包含要在绑定中写入的数据。 传递的值的类型决定将要写入的内容,如下表中所示。

data 写入的数据
字符串 将写入纯文本或可强制转换为字符串的任何内容。
数组的数组(“矩阵”) 将写入不带标题的表格数据。 例如,若要将数据写入三行两列,可以传递如下的数组:\[\["R1C1", "R1C2"\], \["R2C1", "R2C2"\], \["R3C1", "R3C2"\]\]。 若要编写包含三行的单列,请传递如下所示的数组: \[\["R1C1"\], \["R2C1"\], \["R3C1"\]\]
对象TableData 将写入带标题的表格数据。

此外,这些特定于应用程序的操作在将数据写入绑定时适用。 对于Word,指定的数据将写入绑定,如下所示。

data 写入的数据
字符串 写入指定的文本。
数组 (“matrix”) 或 TableData 对象 写入 Word 表格。
HTML 写入指定的 HTML。 如果您写入的任何 HTML 均有效,则 Word 将引发错误。 Word 将尽可能多的写入 HTML,并将省略任何无效数据。
Office Open XML ("Open XML") 写入指定的 XML。

对于 Excel,指定的数据将写入绑定,如下所示。

data 写入的数据
字符串 指定文本将作为第一个绑定单元格的值插入。 您还可以指定一个有效公式,将该公式添加到绑定单元格。 例如,将 data 设置为 "=SUM(A1:A5)" 将计算指定范围中值的总数。 但是,当在绑定单元格中设置公式时,设置后将无法从绑定单元格读取添加的公式(或任何已有公式)。 如果在绑定单元格上调用 Binding.getDataAsync 方法来读取其数据,则该方法只能返回单元格中显示的数据, (公式的结果) 。
数组的数组(“矩阵”),形状与指定绑定的形状完全匹配 写入行和列集。还可以指定包含有效公式的数组数组,以将它们添加到绑定单元格。 例如,将数据设置为 会将 \[\["=SUM(A1:A5)","=AVERAGE(A1:A5)"\]\] 这两个公式添加到包含两个单元格的绑定中。 就像在单个绑定单元格上设置公式一样,无法使用 方法从绑定 Binding.getDataAsync) 读取添加的公式 (或任何预先存在的公式 - 它仅返回绑定单元格中显示的数据。
对象 TableData ,表格的形状与绑定表匹配 写入一组指定的行和/或标题(如果不会覆盖周围单元格中的其他数据)。 **注意**:如果在为 *data* 参数传递的对象中 TableData 指定公式,则可能由于 Excel 的“计算列”功能而无法获得预期的结果,该功能会自动复制列中的公式。 若要在要将包含公式的 *data* 写入绑定表中时解决此问题,请尝试将数据指定为数组数组 (而不是 TableData 对象) ,并将 *coercionType* 指定为 Microsoft.Office.Matrix 或“matrix”。

对于Excel web 版:

  • 在对此方法的单个调用中,传递给数据参数的值中的单元格总数不能超过 20,000。

  • 传递给 cellFormat 参数的格式设置组数不能超过 100。 每个格式设置组由应用于特定单元格范围的一组格式组成。

在其他所有情况下,都会返回错误。

如果指定了可选的 startRow 和 startColumn 参数,并且它们指定了有效的范围,setDataAsync 方法将在表或矩阵绑定的子集中写入数据。

在传递给 setDataAsync 方法的回调函数中,您可以使用 AsyncResult 对象的属性返回以下信息。

属性 用途
AsyncResult.value 始终返回 , undefined 因为没有要检索的对象或数据。
AsyncResult.status 确定操作是成功还是失败。
AsyncResult.error 如果操作失败,则访问提供错误信息的 Error 对象。
AsyncResult.asyncContext 定义在 AsyncResult 对象中返回的任何类型的项,而不进行更改。

setDataAsync(data, callback)

将数据写入指定的绑定对象表示的文档的绑定部分。

setDataAsync(data: TableData | any, callback?: (result: AsyncResult<void>) => void): void;

参数

data

Office.TableData | any

当前选择中要设置的数据。 按 Office 应用程序分类的可能数据类型:

字符串:在 Windows 上Excel web 版和,仅在 Web 上和 Windows 上Word

数组数组:仅限 Excel 和 Word

TableData:仅限 Excel 和 Word

HTML:仅在 Web 和 Windows 上Word

Office Open XML:仅限Word

callback

(result: Office.AsyncResult<void>) => void

可选。 回调返回时调用的函数,其唯一参数的类型为 Office.AsyncResult

返回

void

注解

要求集

为数据传递的值包含要在绑定中写入的数据。 传递的值的类型决定将要写入的内容,如下表中所示。

data 写入的数据
字符串 将写入纯文本或可强制转换为字符串的任何内容。
数组的数组(“矩阵”) 将写入不带标题的表格数据。 例如,若要将数据写入三行两列,可以传递如下的数组:\[\["R1C1", "R1C2"\], \["R2C1", "R2C2"\], \["R3C1", "R3C2"\]\]。 若要编写包含三行的单列,请传递如下所示的数组: \[\["R1C1"\], \["R2C1"\], \["R3C1"\]\]
对象TableData 将写入带标题的表格数据。

此外,这些特定于应用程序的操作在将数据写入绑定时适用。 对于Word,指定的数据将写入绑定,如下所示。

data 写入的数据
字符串 写入指定的文本。
数组 (“matrix”) 或 TableData 对象 写入 Word 表格。
HTML 写入指定的 HTML。 如果您写入的任何 HTML 均有效,则 Word 将引发错误。 Word 将尽可能多的写入 HTML,并将省略任何无效数据。
Office Open XML ("Open XML") 写入指定的 XML。

对于 Excel,指定的数据将写入绑定,如下所示。

data 写入的数据
字符串 指定文本将作为第一个绑定单元格的值插入。 您还可以指定一个有效公式,将该公式添加到绑定单元格。 例如,将 data 设置为 "=SUM(A1:A5)" 将计算指定范围中值的总数。 但是,当在绑定单元格中设置公式时,设置后将无法从绑定单元格读取添加的公式(或任何已有公式)。 如果在绑定单元格上调用 Binding.getDataAsync 方法来读取其数据,则该方法只能返回单元格中显示的数据, (公式的结果) 。
数组的数组(“矩阵”),形状与指定绑定的形状完全匹配 写入行和列集。还可以指定包含有效公式的数组数组,以将它们添加到绑定单元格。 例如,将数据设置为 会将 \[\["=SUM(A1:A5)","=AVERAGE(A1:A5)"\]\] 这两个公式添加到包含两个单元格的绑定中。 就像在单个绑定单元格上设置公式一样,无法使用 方法从绑定 Binding.getDataAsync) 读取添加的公式 (或任何预先存在的公式 - 它仅返回绑定单元格中显示的数据。
对象 TableData ,表格的形状与绑定表匹配 写入一组指定的行和/或标题(如果不会覆盖周围单元格中的其他数据)。 **注意**:如果在为 *data* 参数传递的对象中 TableData 指定公式,则可能由于 Excel 的“计算列”功能而无法获得预期的结果,该功能会自动复制列中的公式。 若要在要将包含公式的 *data* 写入绑定表中时解决此问题,请尝试将数据指定为数组数组 (而不是 TableData 对象) ,并将 *coercionType* 指定为 Microsoft.Office.Matrix 或“matrix”。

对于Excel web 版:

  • 在对此方法的单个调用中,传递给数据参数的值中的单元格总数不能超过 20,000。

  • 传递给 cellFormat 参数的格式设置组数不能超过 100。 每个格式设置组由应用于特定单元格范围的一组格式组成。

在其他所有情况下,都会返回错误。

如果指定了可选的 startRow 和 startColumn 参数,并且它们指定了有效的范围,setDataAsync 方法将在表或矩阵绑定的子集中写入数据。

在传递给 setDataAsync 方法的回调函数中,您可以使用 AsyncResult 对象的属性返回以下信息。

属性 用途
AsyncResult.value 始终返回 , undefined 因为没有要检索的对象或数据。
AsyncResult.status 确定操作是成功还是失败。
AsyncResult.error 如果操作失败,则访问提供错误信息的 Error 对象。
AsyncResult.asyncContext 定义在 AsyncResult 对象中返回的任何类型的项,而不进行更改。

示例

function setBindingData() {
    Office.select("bindings#MyBinding").setDataAsync('Hello World!', function (asyncResult) { });
}

// Specifying the optional coercionType parameter lets you specify the kind of data you want to write to a binding.
// For example, in Word if you want to write HTML to a text binding, you can specify the coercionType parameter 
// as "html" as shown in the following example, which uses HTML <b> tags to make "Hello" bold.
function writeHtmlData() {
    Office.select("bindings#myBinding").setDataAsync(
        "<b>Hello</b> World!", {coercionType: "html"}, 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; 
}

// In this example, the call to setDataAsync passes the data parameter as an array of arrays
// (to create a single column of three rows), and specifies the data structure with the 
// coercionType parameter as a "matrix".
function writeBoundDataMatrix() {
    Office.select("bindings#myBinding").setDataAsync(
        [['Berlin'],['Munich'],['Duisburg']],{ coercionType: "matrix" }, function (asyncResult) {
        if (asyncResult.status == "failed") {
            write('Error: ' + asyncResult.error.message);
        } else {
            write('Bound data: ' + asyncResult.value);
        }
    });
}
// Function that writes to a div with id='message' on the page.
function write(message){
    document.getElementById('message').innerText += message; 
}

// In the writeBoundDataTable function in this example, the call to setDataAsync passes the data parameter 
// as a TableData object (to write three columns and three rows), and specifies the data structure
// with the coercionType parameter as a "table".

// In the updateTableData function, the call to setDataAsync again passes the data parameter as a TableData object,
// but as a single column with a new header and three rows, to update the values in the last column 
// of the table created with the writeBoundDataTable function. The optional zero-based startColumn parameter 
// is specified as 2 to replace the values in the third column of the table.
function writeBoundDataTable() {
    // Create a TableData object.
    const myTable = new Office.TableData();
    myTable.headers = ['First Name', 'Last Name', 'Grade'];
    myTable.rows = [['Kim', 'Abercrombie', 'A'], ['Junmin','Hao', 'C'],['Toni','Poe','B']];

    // Set myTable in the binding.
    Office.select("bindings#myBinding").setDataAsync(myTable, { coercionType: "table" }, 
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed) {
                write('Error: '+ asyncResult.error.message);
        } else {
            write('Bound data: ' + asyncResult.value);
        }
    });
}

// Replace last column with different data.
function updateTableData() {
    const newTable = new Office.TableData();
    newTable.headers = ["Gender"];
    newTable.rows = [["M"],["M"],["F"]];
    Office.select("bindings#myBinding").setDataAsync(newTable, { coercionType: "table", startColumn:2 }, 
        function (asyncResult) {
            if (asyncResult.status == Office.AsyncResultStatus.Failed) {
                write('Error: '+ asyncResult.error.message);
        } else {
            write('Bound data: ' + asyncResult.value);
        }     
    });   
}

// In this example, the following call passes two formatting groups to cellFormat.
Office.select("bindings#myBinding").setDataAsync([['Berlin'],['Munich'],['Duisburg']],
  {cellFormat:[{cells: {row: 1}, format: {fontColor: "yellow"}}, 
      {cells: {row: 3, column: 4}, format: {borderColor: "white", fontStyle: "bold"}}]}, 
  function (asyncResult){});