Поделиться через

Чтение и запись данных в текущую выделенную область документа или электронной таблицы

  • Статья

Объект Document предоставляет методы, с помощью которых можно выполнять операции чтения и записи данных над текущим фрагментом, выделенным пользователем, в документе или электронной таблице. Для этого Document объект предоставляет методы getSelectedDataAsync и setSelectedDataAsync . Кроме того, в данной статье рассказывается, как считывать и записывать данные, а также создавать обработчики событий для обнаружения изменений в выделенном пользователем фрагменте.

Метод getSelectedDataAsync работает только с текущим выбором пользователя. Если необходимо сохранить выделение в документе, чтобы тот же выбор был доступен для чтения и записи в сеансах запуска надстройки, необходимо добавить привязку с помощью метода Bindings.addFromSelectionAsync (или создать привязку с помощью одного из других методов addFrom объекта Bindings ). Сведения о создании привязки к региону документа, а затем о чтении и записи в привязку см. в разделе Привязка к регионам в документе или электронной таблице.

Чтение выбранных данных

В примере ниже показано, как получить данные из выделенного фрагмента в документе с помощью метода getSelectedDataAsync.

Office.context.document.getSelectedDataAsync(Office.CoercionType.Text, function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write('Action failed. Error: ' + asyncResult.error.message);
    }
    else {
        write('Selected data: ' + asyncResult.value);
    }
});

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

В этом примере первый параметр coercionType указывается как Office.CoercionType.Text (этот параметр также можно указать с помощью строки "text"литерала ). Это означает, что свойство value объекта AsyncResult, доступного из параметра asyncResult в функции обратного вызова, возвратит строку, содержащую выделенный текст в документе. Если вы укажете какой-либо другой тип приведения, то получите другие значения. Office.CoercionType — это перечисление значений доступных типов приведений. Office.CoercionType.Text вычисляет строку "text".

Совет

В каких случаях следует использовать для доступа к данным матрицы, а в каких — coercionType? Если выбранные табличные данные должны динамически увеличиваться при добавлении строк и столбцов и работать с заголовками таблиц, следует использовать тип данных таблицы (указав параметр getSelectedDataAsynccoercionType метода как "table" или Office.CoercionType.Table). Добавление строк и столбцов в структуре данных поддерживается как табличными, так и матричными данными, но присоединение строк и столбцов поддерживается только табличными данными. Если вы не планируете добавлять строки и столбцы, а для данных не требуется функциональность заголовка, следует использовать тип данных матрицы (указав параметр getSelectedDataAsynccoercionType метода как "matrix" или Office.CoercionType.Matrix), который предоставляет более простую модель взаимодействия с данными.

Анонимная функция, передаваемая в метод в качестве второго параметра обратного getSelectedDataAsyncвызова, выполняется по завершении операции. При вызове функции передается один параметр asyncResult, который содержит результат и сведения о состоянии вызова. Если вызов завершается ошибкой, свойство AsyncResulterror объекта предоставляет доступ к объекту Error. Вы можете проверить значение свойств Error.name и Error.message, чтобы определить, почему операция завершилась с ошибкой. В противном случае будет отображен выделенный в документе текст.

Свойство AsyncResult.status используется в выражении if для проверки того, успешно ли выполнен вызов. Office.AsyncResultStatus — это перечисление доступных AsyncResult.status значений свойств. Office.AsyncResultStatus.Failed вычисляет строку "failed" (и, опять же, также можно указать как строку литерала).

Запись данных в выделение

В следующем примере показано, как записать в выделение строку "Hello World!".

Office.context.document.setSelectedDataAsync("Hello World!", function (asyncResult) {
    if (asyncResult.status == Office.AsyncResultStatus.Failed) {
        write(asyncResult.error.message);
    }
});

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

Передача разных типов объектов для параметра данных будет иметь разные результаты. Результат зависит от того, что в данный момент выбрано в документе, в каком клиентском приложении Office размещается ваша надстройка, и от того, можно ли принудить переданные данные к текущему выбору.

Анонимная функция, которая передается в метод setSelectedDataAsync в качестве параметра callback, выполняется после завершения асинхронного вызова. При записи данных в выделенный фрагмент с помощью setSelectedDataAsync метода параметр asyncResult обратного вызова предоставляет доступ только к состоянию вызова и к объекту Error в случае сбоя вызова.

Обнаружение изменений в выделенной области

В примере ниже показано, как определять изменения в выделенном фрагменте, используя метод Document.addHandlerAsync для добавления обработчика события SelectionChanged в документе.

Office.context.document.addHandlerAsync("documentSelectionChanged", myHandler, function(result){}
);

// Event handler function.
function myHandler(eventArgs){
    write('Document Selection Changed');
}

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

Первый параметр eventType указывает имя события, на которое нужно подписаться. Передача строки "documentSelectionChanged" для этого параметра эквивалентна передаче Office.EventType.DocumentSelectionChanged типа события перечисления Office.EventType .

Функция, передаваемая myHandler() в метод в качестве второго параметра, обработчика, является обработчиком событий, который выполняется при изменении выделения в документе. При вызове этой функции передается единственный параметр eventArgs, который после завершения асинхронной операции будет содержать ссылку на объект DocumentSelectionChangedEventArgs. Вы можете использовать свойство DocumentSelectionChangedEventArgs.document для доступа к документу, создавшему событие.

Примечание.

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

Отключение обнаружения изменений в выделении

В примере ниже показано, как остановить прослушивание события Document.SelectionChanged, вызвав метод document.removeHandlerAsync.

Office.context.document.removeHandlerAsync("documentSelectionChanged", {handler:myHandler}, function(result){});

Имя myHandler функции, передаваемой в качестве второго параметра, обработчика, указывает обработчик событий, который будет удален из SelectionChanged события.

Важно!

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