Привязка к областям в документе или электронной таблице

Привязки позволяют надстройке согласованно обращаться к определенным регионам документа или электронной таблицы. Привязка — это закладка, которая запоминает определенное расположение, даже если пользователи изменяют свой выбор или переходят в другое место документа. В частности, вот какие привязки предлагают надстройку.

• Доступ к общим структурам данных в поддерживаемых приложениях Office, таких как таблицы, диапазоны или текст.
• Чтение и запись данных без необходимости выбора пользователей.
• Создание постоянных связей между надстройкой и данными документа. Привязки сохраняются вместе с документом и работают между сеансами.

Чтобы создать привязку, вызовите один из следующих методов объекта Bindings , чтобы связать область документа с уникальным идентификатором: addFromPromptAsync, addFromSelectionAsync или addFromNamedItemAsync. После создания привязки используйте ее идентификатор для чтения из этого региона или записи в нее в любое время.

Вы также можете подписаться на события изменения данных и выбора для определенных привязанных регионов. Это означает, что надстройка получает уведомления только об изменениях в связанной области, а не во всем документе.

Выбор подходящего типа привязки

Office поддерживает три разных типа привязок. Тип указывается с помощью параметра bindingType при создании привязки с помощью addFromSelectionAsync, addFromPromptAsync или addFromNamedItemAsync.

Привязка текста

Текстовая привязка — привязывается к области документа, которая может быть представлена в виде текста.

В Word большинство смежных вариантов выбора работают. В Excel только для выделения отдельных ячеек можно использовать текстовую привязку. Excel поддерживает только обычный текст, в то время как Word поддерживает три формата: обычный текст, HTML и Open XML для Office.

Матричная привязка

Привязка матрицы — привязка к фиксированной области, содержащей табличные данные без заголовков.

Данные в матричной привязке считываются или записываются как двумерный массив (массив массивов в JavaScript). Например, две строки строковых значений в двух столбцах будут выглядеть как [['a', 'b'], ['c', 'd']], а один столбец из трех строк — [['a'], ['b'], ['c']].

В Excel любое непрерывное выделение ячеек работает для привязки матрицы. В Word матричная привязка поддерживается только таблицами.

Привязка таблицы

Привязка таблицы — привязывается к области документа, содержащей таблицу с заголовками.

Данные в привязке таблицы считываются или записываются как объект TableData . Объект TableData предоставляет данные через headers свойства и rows .

Любая таблица Excel или Word может быть основой для табличной привязки. После установки привязки таблицы новые строки или столбцы, добавляемые пользователями в таблицу, автоматически включаются в привязку.

После создания привязки с одним из трех методов addFrom можно работать с данными и свойствами привязки, используя соответствующий объект MatrixBinding, TableBinding или TextBinding. Все три объекта наследуют методы getDataAsync и setDataAsync от Binding объекта для взаимодействия с привязанными данными.

Создание привязки из текущего выделенного фрагмента

В следующем примере к текущему выделенному фрагменту добавляется текстовая привязка myBinding с помощью метода addFromSelectionAsync .

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

В этом примере тип привязки — text, поэтому для выделенного фрагмента создается объект TextBinding . Различные типы привязок предоставляют различные данные и операции. Office.BindingType — это перечисление доступных типов привязки.

Второй необязательный параметр указывает идентификатор новой привязки. Если не указать идентификатор, он создается автоматически.

Анонимная функция, переданная в качестве последнего параметра обратного вызова , запускается по завершении создания привязки. Функция получает один параметр , asyncResultкоторый предоставляет доступ к объекту AsyncResult с состоянием вызова. Свойство AsyncResult.value содержит ссылку на объект Binding указанного типа для созданной привязки. Вы можете использовать этот объект Binding для получения и задания данных.

Создание привязки из запроса

Следующая функция добавляет текстовую привязку с именем myBinding с помощью метода addFromPromptAsync . Этот метод позволяет пользователям указывать диапазон для привязки с помощью встроенного запроса на выбор диапазона приложения.

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

В этом примере тип привязки — text, поэтому для выбора пользователем в командной строке создается объект TextBinding .

Второй параметр содержит идентификатор новой привязки. Если не указать идентификатор, он создается автоматически.

Анонимная функция, переданная в качестве третьего параметра обратного вызова , запускается по завершении создания привязки. При запуске функции обратного вызова объект AsyncResult содержит состояние вызова и только что созданную привязку.

На следующем снимке экрана показан встроенный запрос на выбор диапазона в Excel.

Добавление привязки к именованному элементу

Следующая функция добавляет привязку к существующему myRange именованный элемент в виде матричной привязки с помощью метода addFromNamedItemAsync и назначает привязке 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; 
}

Для ExcelitemName параметр addFromNamedItemAsync ссылается на существующий именованный диапазон, диапазон, указанный в стиле ссылки A1 ("A1:A3"), или таблицу. По умолчанию Excel назначает имена "Table1" для первой таблицы, "Table2" для второй таблицы и т. д. Чтобы назначить понятное имя таблице в пользовательском интерфейсе Excel, используйте свойство Имя таблицы в средствах для таблиц | Вкладка Конструктор .

Следующая функция создает привязку в Excel к первым трем ячейкам в столбце A ("A1:A3"), назначает идентификатор "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; 
}

Для WorditemName параметр addFromNamedItemAsync ссылается на Title свойство Rich Text элемента управления содержимым. (Rich Text — единственный элемент управления содержимым, поддерживающий привязку.)

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

Следующая функция создает текстовую привязку в Word к элементу управления содержимым форматированного текста с именем "FirstName", присваивает идентификатор"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; 
}

Получение всех привязок

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

Получение привязки по идентификатору с помощью getByIdAsync

В следующем примере метод getByIdAsync используется для получения привязки в документе путем указания ее идентификатора. В этом примере предполагается, что привязка с именем '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 параметром является идентификатор извлекаемой привязки.

Анонимная функция, переданная в качестве второго параметра обратного вызова , запускается по завершении операции. Функция вызывается с одним параметром asyncResult, который содержит состояние вызова и привязку с идентификатором myBinding.

Получение привязки по идентификатору с помощью Office.select

В следующем примере функция Office.select используется для получения обещания объекта 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. Если обещание не может вернуть объект Binding, обратный onError вызов можно использовать для доступа к объекту asyncResult.error для получения дополнительных сведений. Если необходимо вызвать член объекта Binding, отличный от четырех методов, предоставляемых обещанием объекта Binding , возвращенным select функцией, вместо этого используйте метод getByIdAsync с помощью свойства Document.bindings и метода getByIdAsync для получения объекта Binding .

Отмена привязки по идентификатору

В следующем примере метод releaseByIdAsync используется для освобождения привязки в документе путем указания ее идентификатора.

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 параметром является идентификатор привязки для освобождения.

Анонимная функция, передаваемая в качестве второго параметра, является обратным вызовом, который выполняется после завершения операции. Функция вызывается с одним параметром 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 для доступа к привязке по ее идентификатору и начать вызов метода getDataAsync , как показано ниже:

Office.select("bindings#myBindingID").getDataAsync

Анонимная функция, передаваемая в метод, является обратным вызовом, который выполняется после завершения операции. Свойство AsyncResult.value содержит данные в myBinding. Тип значения зависит от типа привязки. Привязка в этом примере является текстовой привязкой, поэтому значение будет содержать строку. Дополнительные примеры работы с матричными и табличными привязками представлены в статье, посвященной методу getDataAsync.

Запись данных в привязку

В следующем примере метод setDataAsync используется для задания данных в существующей привязке.

myBinding.setDataAsync('Hello World!', function (asyncResult) { });

myBinding — переменная, содержащая существующую текстовую привязку в документе.

В этом примере первым параметром является значение, заданное для myBindingпараметра . Так как привязка текстовая, этим значением будет string. Привязки разных типов принимают разные типы данных.

Анонимная функция, передаваемая в метод, является обратным вызовом, который выполняется после завершения операции. Функция вызывается с одним параметром , asyncResultкоторый содержит состояние результата.

Обнаружение изменений в данных или выборе в привязке

Следующая функция присоединяет обработчик событий к событию DataChanged привязки с идентификатором MyBinding.

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 — переменная, содержащая существующую текстовую привязку в документе.

Первый параметр eventTypeобъекта addHandlerAsync указывает имя события, на которое нужно подписаться. Office.EventType — это перечисление доступных значений типов событий. Office.EventType.BindingDataChanged вычисляет строку bindingDataChanged.

Функция, передаваемая dataChanged в качестве второго параметра обработчика , является обработчиком событий, который выполняется при изменении данных в привязке. Функция вызывается с одним параметром eventArgs, который содержит ссылку на привязку. Эта привязка может использоваться для получения обновленных данных.

Аналогичным образом вы можете обнаруживать, когда пользователь изменяет выделенный фрагмент в привязке, присоединив обработчик события к событию SelectionChanged привязки. Для этого укажите eventType параметр addHandlerAsync как Office.EventType.BindingSelectionChanged или "bindingSelectionChanged".

Для данного события можно добавить несколько обработчиков событий, снова вызвав метод addHandlerAsync и передав дополнительную функцию обработчика событий для handler параметра. Имя каждой функции обработчика событий должно быть уникальным.

Удаление обработчика события

Чтобы удалить обработчик событий для события, вызовите метод removeHandlerAsync , передав тип события в качестве первого параметра eventType , и имя функции обработчика событий, удаляемой в качестве второго параметра обработчика . Например, следующая функция удаляет функцию обработчика dataChanged событий, добавленную в примере предыдущего раздела.

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

См. также

• Общие сведения об API JavaScript для Office
• Асинхронное программирование в надстройках для Office
• Считывание и запись данных в активное выделение документа или таблицы