Office.Bindings interface

获取一个 Office.Document 对象，该对象代表与此绑定集关联的文档。

document: Document;

属性值

Office.Document

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

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结果的属性是 Binding 对象，该对象代表指定的命名项。

返回

void

注解

要求集：

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

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

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

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

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

注意：在Word中，如果有多个格式文本内容控件具有相同的 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 == '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 == '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: 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结果的属性是 Binding 对象，该对象代表指定的命名项。

返回

void

注解

MatrixBindings、 TableBindings、 TextBindings

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

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

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

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

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

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

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

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结果的属性是 Binding 对象，表示用户指定的选择。

返回

void

注解

要求集：不在集中

将指定类型的绑定对象添加到 Bindings 集合，该集合将使用提供的 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: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

参数

bindingType: Office.BindingType

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

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

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

返回

void

注解

要求集：不在集中

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

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

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结果的属性是 Binding 对象，表示用户指定的选择。

返回

void

注解

要求集：

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

注意在 Excel 中，如果调用 addFromSelectionAsync 方法传入现有绑定的 Binding.id，则将使用该绑定的 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: BindingType, callback?: (result: AsyncResult<Binding>) => void): void;

参数

bindingType: Office.BindingType

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

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

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

返回

void

注解

要求集：

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

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

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

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?: (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: 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 指定的 Binding 对象。

返回

void

注解

要求集：

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

基于绑定的名称检索绑定

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

参数

id: string

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

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

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

返回

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

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

属性值

方法详细信息

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)

参数

返回

注解

示例

其他资源