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

Имя привязываемого объекта в документе. Например, таблица MyExpenses в Excel.

bindingType

Office.BindingType

Тип Office.BindingType для данных. Метод возвращает значение NULL, если выбранный объект не может быть принудован к указанному типу.

options

Office.AddBindingFromNamedItemOptions

Предоставляет параметры для настройки созданной привязки.

callback

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

Необязательный параметр. Функция, вызываемая при возврате обратного вызова, единственный параметр которой имеет тип Office.AsyncResult. Свойством value результата является объект Binding, представляющий указанный именованный элемент.

Возвращаемое значение

void

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

Для Excel параметр itemName может ссылаться на именованный диапазон или таблицу.

По умолчанию при добавлении таблиц в Excel имя "Table1" назначается первой добавленной таблице, "Table2" — второй таблице и так далее. Чтобы назначить понятное имя для таблицы в пользовательском интерфейсе Excel, используйте свойство Имя таблицы в | Вкладка "Конструктор" на ленте.

Примечание. В Excel при указании таблицы в качестве именованного элемента необходимо полностью указать имя, чтобы включить имя листа в имя таблицы в следующем формате: "Лист1! Table1"

Для Word параметр itemName ссылается на свойство Title элемента управления содержимым форматированного текста. (Нельзя привязать к элементам управления содержимым, кроме элемента управления содержимым в формате форматированного текста.

По умолчанию элементу управления содержимым не назначено значение Title. Чтобы назначить понятное имя в пользовательском интерфейсе Word, после вставки элемента управления контентом Форматированный текст из группы Элементы управления на вкладке Разработчик ленты выберите команду Свойства в группе Элементы управления, чтобы открыть диалоговое окно Свойства элемента управления контентом. Затем задайте для свойства Title элемента управления контентом имя, на которое вы будете ссылаться в коде.

Примечание. Если в Word есть несколько элементов управления с содержимым форматированного текста с одним и тем же значением свойства title (name) и вы пытаетесь привязать к одному из этих элементов управления с помощью этого метода (указав его имя в качестве параметра 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, bindingType, callback)

Создает привязку для именованного объекта в документе.

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

Параметры

itemName

string

Имя привязываемого объекта в документе. Например, таблица MyExpenses в Excel.

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, используйте свойство Имя таблицы в | Вкладка "Конструктор" на ленте.

Примечание. В Excel при указании таблицы в качестве именованного элемента необходимо полностью указать имя, чтобы включить имя листа в имя таблицы в следующем формате: "Лист1! Table1"

Для Word параметр itemName ссылается на свойство Title элемента управления содержимым форматированного текста. (Нельзя привязать к элементам управления содержимым, кроме элемента управления содержимым в формате форматированного текста.

По умолчанию элементу управления содержимым не назначено значение Title. Чтобы назначить понятное имя в пользовательском интерфейсе Word, после вставки элемента управления контентом Форматированный текст из группы Элементы управления на вкладке Разработчик ленты выберите команду Свойства в группе Элементы управления, чтобы открыть диалоговое окно Свойства элемента управления контентом. Затем задайте для свойства Title элемента управления контентом имя, на которое вы будете ссылаться в коде.

Примечание. Если в Word есть несколько элементов управления с содержимым форматированного текста с одним и тем же значением свойства title (name) и вы пытаетесь привязать к одному из этих элементов управления с помощью этого метода (указав его имя в качестве параметра 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 результата является объект Binding, представляющий выбор, заданный пользователем.

Возвращаемое значение

void

Комментарии

Набор обязательных требований: не в наборе

Добавляет объект привязки указанного типа в коллекцию Bindings, которая будет идентифицироваться по указанному идентификатору. Метод завершается ошибкой, если заданную выборку невозможно привязать.

Примеры

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 результата является объект Binding, представляющий выбор, заданный пользователем.

Возвращаемое значение

void

Комментарии

Набор обязательных требований: не в наборе

Добавляет объект привязки указанного типа в коллекцию Bindings, которая будет идентифицироваться по указанному идентификатору. Метод завершается ошибкой, если заданную выборку невозможно привязать.

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 результата является объект Binding, представляющий выбор, заданный пользователем.

Возвращаемое значение

void

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

Добавляет указанный тип объекта привязки в коллекцию Bindings, которая будет определена по указанному идентификатору.

Примечание. Если в Excel вызывается метод addFromSelectionAsync, передавая Binding.id существующей привязки, используется тип Binding.type этой привязки, и его тип нельзя изменить, указав другое значение для параметра bindingType. Если необходимо использовать существующий идентификатор и изменить 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 результата является объект Binding, представляющий выбор, заданный пользователем.

Возвращаемое значение

void

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

Добавляет указанный тип объекта привязки в коллекцию Bindings, которая будет определена по указанному идентификатору.

Примечание. Если в Excel вызывается метод addFromSelectionAsync, передавая Binding.id существующей привязки, используется тип Binding.type этой привязки, и его тип нельзя изменить, указав другое значение для параметра bindingType. Если необходимо использовать существующий идентификатор и изменить 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

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

getAllAsync(callback)

Получает все ранее созданные привязки.

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

Параметры

callback

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

Функция, вызываемая при возврате обратного вызова, единственный параметр которой имеет тип Office.AsyncResult. Свойство value результата представляет собой массив, содержащий каждую привязку, созданную для объекта Bindings, на который ссылается ссылка.

Возвращаемое значение

void

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

Примеры

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 результата является объект Binding, заданный идентификатором в вызове.

Возвращаемое значение

void

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

Сбой, если указанный идентификатор не существует.

getByIdAsync(id, callback)

Извлекает привязку на основе ее имени.

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

Параметры

id

string

Задает уникальное имя объекта привязки. Обязательно.

callback

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

Необязательный параметр. Функция, вызываемая при возврате обратного вызова, единственный параметр которой имеет тип Office.AsyncResult. Свойством value результата является объект Binding, заданный идентификатором в вызове.

Возвращаемое значение

void

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

Сбой, если указанный идентификатор не существует.

Примеры

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

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

Сбой, если указанный идентификатор не существует.

releaseByIdAsync(id, callback)

Удаляет привязку из документа

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

Параметры

id

string

Задает уникальное имя, используемое для идентификации объекта привязки. Обязательно.

callback

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

Необязательный параметр. Функция, вызываемая при возврате обратного вызова, единственный параметр которой имеет тип Office.AsyncResult.

Возвращаемое значение

void

Комментарии

Наборы обязательных элементов:

• MatrixBindings

• TableBindings

• TextBindings

Сбой, если указанный идентификатор не существует.

Примеры

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