Office.Bindings interface

表示外接程序在文档中所具有的绑定。

注解

使用方

Office.Document：绑定

属性

获取表示与这组绑定关联的文档的 Office.Document 对象。

方法

addFromNamedItemAsync(itemName, bindingType, options, callback)	创建针对文档中命名对象的绑定。
addFromNamedItemAsync(itemName, bindingType, callback)	创建针对文档中命名对象的绑定。
addFromPromptAsync(bindingType, options, callback)	通过提示用户在文档上进行选择来创建绑定。
addFromPromptAsync(bindingType, callback)	通过提示用户在文档上进行选择来创建绑定。
addFromSelectionAsync(bindingType, options, callback)	根据用户的当前选择创建绑定。
addFromSelectionAsync(bindingType, callback)	根据用户的当前选择创建绑定。
getAllAsync(options, callback)	获取先前创建的所有绑定。
getAllAsync(callback)	获取先前创建的所有绑定。
getByIdAsync(id, options, callback)	根据绑定的名称检索绑定
getByIdAsync(id, callback)	根据绑定的名称检索绑定
releaseByIdAsync(id, options, callback)	从文档中删除绑定
releaseByIdAsync(id, callback)	从文档中删除绑定

document

获取表示与这组绑定关联的文档的 Office.Document 对象。

document: Document;

属性值

Office.Document

addFromNamedItemAsync(itemName, bindingType, options, callback)

创建针对文档中命名对象的绑定。

addFromNamedItemAsync(itemName: string, bindingType: BindingType, options?: AddBindingFromNamedItemOptions, callback?: (result: AsyncResult<Binding>) => void): void;

参数

itemName: string

文档中可绑定对象的名称。例如，Excel 中的'MyExpenses'表。”

bindingType: Office.BindingType

数据的 Office.BindingType 。如果无法将所选对象强制转换为指定类型，则该方法返回 null。

options: Office.AddBindingFromNamedItemOptions

提供用于配置创建的绑定的选项。

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

可选。回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是表示指定命名项的绑定对象。

返回

void

注解

要求集：

对于 Excel，itemName 参数可以引用命名区域或表。

默认情况下，在 Excel 中添加表会为你添加的第一个表分配名称“Table1”，为你添加的第二个表分配名称“Table2”，以此类推。若要在 Excel UI 中为表分配有意义的名称，请使用“表工具 |功能区的“设计”选项卡。

注意：在 Excel 中，将表指定为命名项时，必须完全限定名称，才能在采用以下格式的表名称中包含工作表名称：“Sheet1！Table1”

对于 Word，itemName 参数引用 RTF 内容控件的 Title 属性。 (不能绑定到富文本内容控件) 以外的内容控件。

默认情况下，未向内容控件分配任何 Title 值。若要在 Word UI 中分配有意义的名称，请从功能区的“开发人员”选项卡上的“控件”组中插入一个“格式文本”内容控件，并使用“控件”组中的“属性”命令显示“内容控件属性”对话框。然后将内容控件的“标题”属性设置为需要从代码中引用的名称。

注意：在 Word 中，如果有多个 RTF 内容控件具有相同的 Title 属性值 (名称) ，并且你尝试使用此方法 (将其名称指定为 itemName 参数) 来绑定到其中一个内容控件，则操作将失败。

示例

// The following example adds a binding to the myRange named item in Excel as a "matrix" binding,
// and assigns the binding's id as myMatrix.
function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync(
        "myRange", "matrix", {id:'myMatrix'}, function (result) {
        if (result.status === Office.AsyncResultStatus.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;
}

// The following example adds a binding to the Table1 named item in Excel as a "table" binding,
// and assigns the binding's id as myTable.
function bindNamedItem() {
    Office.context.document.bindings.addFromNamedItemAsync(
        "Table1", "table", {id:'myTable'}, function (result) {
        if (result.status === Office.AsyncResultStatus.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;
}

// The following example creates a text binding in Word to a rich text content control named "FirstName",
// assigns the id "firstName", and then displays that information.
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;
}

addFromNamedItemAsync(itemName, bindingType, callback)

创建针对文档中命名对象的绑定。

addFromNamedItemAsync(itemName: string, bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

参数

itemName: string

文档中可绑定对象的名称。例如，Excel 中的'MyExpenses'表。”

bindingType: Office.BindingType

数据的 Office.BindingType 。如果无法将所选对象强制转换为指定类型，则该方法返回 null。

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

可选。回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是表示指定命名项的绑定对象。

返回

void

注解

MatrixBindings、 TableBindings、 TextBindings

对于 Excel，itemName 参数可以引用命名区域或表。

默认情况下，在 Excel 中添加表会为你添加的第一个表分配名称“Table1”，为你添加的第二个表分配名称“Table2”，以此类推。若要在 Excel UI 中为表分配有意义的名称，请使用“表工具 |功能区的“设计”选项卡。

注意：在 Excel 中，将表指定为命名项时，必须完全限定名称，才能在采用以下格式的表名称中包含工作表名称：“Sheet1！Table1”

对于 Word，itemName 参数引用 RTF 内容控件的 Title 属性。 (不能绑定到富文本内容控件) 以外的内容控件。

默认情况下，未向内容控件分配任何 Title 值。若要在 Word UI 中分配有意义的名称，请从功能区的“开发人员”选项卡上的“控件”组中插入一个“格式文本”内容控件，并使用“控件”组中的“属性”命令显示“内容控件属性”对话框。然后将内容控件的“标题”属性设置为需要从代码中引用的名称。

注意：在 Word 中，如果有多个 RTF 内容控件具有相同的 Title 属性值 (名称) ，并且你尝试使用此方法 (将其名称指定为 itemName 参数) 来绑定到其中一个内容控件，则操作将失败。

addFromPromptAsync(bindingType, options, callback)

通过提示用户在文档上进行选择来创建绑定。

addFromPromptAsync(bindingType: BindingType, options?: AddBindingFromPromptOptions, callback?: (result: AsyncResult<Binding>) => void): void;

参数

bindingType: Office.BindingType

指定要创建的绑定对象的类型。必填。如果无法将所选对象强制转换为指定类型，则返回 null。

options: Office.AddBindingFromPromptOptions

提供用于配置提示和标识创建的绑定的选项。

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

可选。回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是表示用户所指定选择的绑定对象。

返回

void

注解

要求集：不在集合中

将指定类型的绑定对象添加到绑定集合，该集合将使用提供的 ID 进行标识。如果无法绑定指定选择，则该方法会失败。

示例

function addBindingFromPrompt() {
    Office.context.document.bindings.addFromPromptAsync(
        Office.BindingType.Text, 
        { id: 'MyBinding', promptText: 'Select text to bind to.' },
        function (asyncResult) {
            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;
}

addFromPromptAsync(bindingType, callback)

通过提示用户在文档上进行选择来创建绑定。

addFromPromptAsync(bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

参数

bindingType: Office.BindingType

指定要创建的绑定对象的类型。必填。如果无法将所选对象强制转换为指定类型，则返回 null。

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

可选。回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是表示用户所指定选择的绑定对象。

返回

void

注解

要求集：不在集合中

将指定类型的绑定对象添加到绑定集合，该集合将使用提供的 ID 进行标识。如果无法绑定指定选择，则该方法会失败。

addFromSelectionAsync(bindingType, options, callback)

根据用户的当前选择创建绑定。

addFromSelectionAsync(bindingType: BindingType, options?: AddBindingFromSelectionOptions, callback?: (result: AsyncResult<Binding>) => void): void;

参数

bindingType: Office.BindingType

指定要创建的绑定对象的类型。必填。如果无法将所选对象强制转换为指定类型，则返回 null。

options: Office.AddBindingFromSelectionOptions

提供用于标识所创建绑定的选项。

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

可选。回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是表示用户所指定选择的绑定对象。

返回

void

注解

要求集：

将指定类型的绑定对象添加到绑定集合，该集合将使用提供的 ID 进行标识。

注意在 Excel 中，如果调用传入现有绑定 Binding.id 的 addFromSelectionAsync 方法，则将使用该绑定的 Binding.type，并且不能通过为 bindingType 参数指定其他值来更改其类型。如果需要使用现有 ID 并更改 bindingType，请首先调用 Bindings.releaseByIdAsync 方法以释放绑定，然后调用 addFromSelectionAsync 方法以使用新类型重新建立绑定。

示例

function addBindingFromSelection() {
    Office.context.document.bindings.addFromSelectionAsync(Office.BindingType.Text, { id: 'MyBinding' }, 
        function (asyncResult) {
            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;
}

addFromSelectionAsync(bindingType, callback)

根据用户的当前选择创建绑定。

addFromSelectionAsync(bindingType: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

参数

bindingType: Office.BindingType

指定要创建的绑定对象的类型。必填。如果无法将所选对象强制转换为指定类型，则返回 null。

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

可选。回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是表示用户所指定选择的绑定对象。

返回

void

注解

要求集：

将指定类型的绑定对象添加到绑定集合，该集合将使用提供的 ID 进行标识。

注意在 Excel 中，如果调用传入现有绑定 Binding.id 的 addFromSelectionAsync 方法，则将使用该绑定的 Binding.type，并且不能通过为 bindingType 参数指定其他值来更改其类型。如果需要使用现有 ID 并更改 bindingType，请首先调用 Bindings.releaseByIdAsync 方法以释放绑定，然后调用 addFromSelectionAsync 方法以使用新类型重新建立绑定。

getAllAsync(options, callback)

获取先前创建的所有绑定。

getAllAsync(options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Binding[]>) => void): void;

参数

options: Office.AsyncContextOptions

提供用于保留任何类型的上下文数据（不变）以供回调使用的选项。

callback: (result: Office.AsyncResult<Office.Binding[]>) => void

回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是一个数组，其中包含为引用的 Bindings 对象创建的每个绑定。

返回

void

注解

要求集：

getAllAsync(callback)

获取先前创建的所有绑定。

getAllAsync(callback?: (result: AsyncResult<Binding[]>) => void): void;

参数

callback: (result: Office.AsyncResult<Office.Binding[]>) => void

回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是一个数组，其中包含为引用的 Bindings 对象创建的每个绑定。

返回

void

注解

要求集：

示例

function displayAllBindingNames() {
    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;
}

getByIdAsync(id, options, callback)

根据绑定的名称检索绑定

getByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<Binding>) => void): void;

参数

id: string

指定绑定对象的唯一名称。必填。

options: Office.AsyncContextOptions

提供用于保留任何类型的上下文数据（不变）以供回调使用的选项。

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

可选。回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是由调用中的 ID 指定的绑定对象。

返回

void

注解

要求集：

如果指定的 ID 不存在则失败。

getByIdAsync(id, callback)

根据绑定的名称检索绑定

getByIdAsync(id: string, callback?: (result: AsyncResult<Binding>) => void): void;

参数

id: string

指定绑定对象的唯一名称。必填。

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

可选。回调返回时调用的函数，其唯一参数的类型为 Office.AsyncResult。 value结果的属性是由调用中的 ID 指定的绑定对象。

返回

void

注解

要求集：

如果指定的 ID 不存在则失败。

示例

function displayBindingType() {
    Office.context.document.bindings.getByIdAsync('MyBinding', function (asyncResult) {
        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;
}

releaseByIdAsync(id, options, callback)

从文档中删除绑定

releaseByIdAsync(id: string, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

参数

id: string

指定要用于标识绑定对象的唯一名称。必填。

options: Office.AsyncContextOptions

提供用于保留任何类型的上下文数据（不变）以供回调使用的选项。

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

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

返回

void

注解

要求集：

如果指定的 ID 不存在则失败。

releaseByIdAsync(id, callback)

从文档中删除绑定

releaseByIdAsync(id: string, callback?: (result: AsyncResult<void>) => void): void;

参数

id: string

指定要用于标识绑定对象的唯一名称。必填。

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

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

返回

void

注解

要求集：

如果指定的 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;
}

注解

使用方

属性

方法

属性详细信息

document

属性值

方法详细信息

addFromNamedItemAsync(itemName, bindingType, options, callback)

参数

返回

注解

示例

addFromNamedItemAsync(itemName, bindingType, callback)

参数

返回

注解

addFromPromptAsync(bindingType, options, callback)

参数

返回

注解

示例

addFromPromptAsync(bindingType, callback)

参数

返回

注解

addFromSelectionAsync(bindingType, options, callback)

参数

返回

注解

示例

addFromSelectionAsync(bindingType, callback)

参数

返回

注解

getAllAsync(options, callback)

参数

返回

注解

getAllAsync(callback)

参数

返回

注解

示例

getByIdAsync(id, options, callback)

参数

返回

注解

getByIdAsync(id, callback)

参数

返回

注解

示例

releaseByIdAsync(id, options, callback)

参数

返回

注解

releaseByIdAsync(id, callback)

参数

返回

注解

示例

反馈