Office.Settings interface

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

Настройки, созданные с помощью методов объекта, Settings сохраняются для каждой надстройки и для каждого документа. Таким образом, они доступны только для создавшего их приложения и только из того документа, в котором они сохранены.

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

Объект Settings автоматически загружается как часть Document объекта и доступен путем вызова свойства settings этого объекта при активации надстройки.

Разработчик отвечает за вызов saveAsync метода после добавления или удаления параметров для сохранения настроек в документе.

Используется

Методы

addHandlerAsync(eventType, handler, options, callback)	Добавляет обработчик события для `settingsChanged` события. Важно! Код надстройки может зарегистрировать обработчик для `settingsChanged` этого события, когда надстройка выполняется в любом клиенте Excel, но событие запускается только в том случае, если надстройка загружена в электронную таблицу, открытую в Excel в Интернете, и несколько пользователей редактируют электронную таблицу (совместно редактируя ее). Таким образом, фактически `settingsChanged` событие поддерживается только в Excel в Интернете в сценариях совместного редактирования.
addHandlerAsync(eventType, handler, callback)	Добавляет обработчик события для `settingsChanged` события. Важно! Код надстройки может зарегистрировать обработчик для `settingsChanged` этого события, когда надстройка выполняется в любом клиенте Excel, но событие запускается только в том случае, если надстройка загружена в электронную таблицу, открытую в Excel в Интернете, и несколько пользователей редактируют электронную таблицу (совместно редактируя ее). Таким образом, фактически `settingsChanged` событие поддерживается только в Excel в Интернете в сценариях совместного редактирования.
get(name)	Извлекает указанный параметр.
refreshAsync(callback)	Считывает все параметры, сохраненные в документе, и обновляет копию этих параметров в памяти для контентной надстройки или надстройки области задач.
remove(name)	Удаляет указанный параметр. Важно! Имейте в виду, что метод `Settings.remove` влияет только на копию контейнера свойств параметров в памяти. Чтобы сохранить удаление указанного параметра в документе, в какой-то момент после вызова `Settings.remove` метода и до закрытия надстройки необходимо вызвать `Settings.saveAsync` метод.
removeHandlerAsync(eventType, options, callback)	Удаляет обработчик событий.`settingsChanged`
removeHandlerAsync(eventType, callback)	Удаляет обработчик событий.`settingsChanged`
saveAsync(options, callback)	Хранится в копии контейнера свойств параметров в документе, содержащейся в памяти.
saveAsync(callback)	Хранится в копии контейнера свойств параметров в документе, содержащейся в памяти.
set(name, value)	Устанавливает или создает указанный параметр. Важно! Имейте в виду, что метод `Settings.set` влияет только на копию контейнера свойств параметров в памяти. Чтобы убедиться, что дополнения или изменения параметров будут доступны для вашей надстройки при следующем открытии документа, в какой-то момент после вызова `Settings.set` метода и до закрытия надстройки, необходимо вызвать `Settings.saveAsync` метод для сохранения параметров в документе.

addHandlerAsync(eventType, handler, options, callback)

Добавляет обработчик события для settingsChanged события.

Важно! Код надстройки может зарегистрировать обработчик для settingsChanged этого события, когда надстройка выполняется в любом клиенте Excel, но событие запускается только в том случае, если надстройка загружена в электронную таблицу, открытую в Excel в Интернете, и несколько пользователей редактируют электронную таблицу (совместно редактируя ее). Таким образом, фактически settingsChanged событие поддерживается только в Excel в Интернете в сценариях совместного редактирования.

addHandlerAsync(eventType: Office.EventType, handler: any, options?: Office.AsyncContextOptions, callback?: (result: AsyncResult<void>) => void): void;

Параметры

eventType: Office.EventType

Указывает тип добавляемого события. Обязательно.

handler: any

Добавляемая функция обработчика событий, единственный параметр которой имеет тип Office.SettingsChangedEventArgs. Обязательно.

options: Office.AsyncContextOptions

Предоставляет возможность сохранения контекстных данных любого типа без изменений для использования в обратном вызове.

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

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

Property	Использовать
`AsyncResult.value`	Всегда возвращается `undefined` , так как при добавлении обработчика события нет данных или объекта для получения.
`AsyncResult.status`	Определяет, удалось ли выполнить операцию.
`AsyncResult.error`	Получите доступ к объекту `Error` , предоставляющему сведения об ошибке, если операция завершилась сбоем.
`AsyncResult.asyncContext`	Определите элемент любого типа, который возвращается в объекте `AsyncResult` без изменений.

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

void

addHandlerAsync(eventType, handler, callback)

Добавляет обработчик события для settingsChanged события.

Важно! Код надстройки может зарегистрировать обработчик для settingsChanged этого события, когда надстройка выполняется в любом клиенте Excel, но событие запускается только в том случае, если надстройка загружена в электронную таблицу, открытую в Excel в Интернете, и несколько пользователей редактируют электронную таблицу (совместно редактируя ее). Таким образом, фактически settingsChanged событие поддерживается только в Excel в Интернете в сценариях совместного редактирования.

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): void;

Параметры

eventType: Office.EventType

Указывает тип добавляемого события. Обязательно.

handler: any

Добавляемая функция обработчика событий, единственный параметр которой имеет тип Office.SettingsChangedEventArgs. Обязательно.

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

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

Property	Использовать
`AsyncResult.value`	Всегда возвращается `undefined` , так как при добавлении обработчика события нет данных или объекта для получения.
`AsyncResult.status`	Определяет, удалось ли выполнить операцию.
`AsyncResult.error`	Получите доступ к объекту `Error` , предоставляющему сведения об ошибке, если операция завершилась сбоем.
`AsyncResult.asyncContext`	Определите элемент любого типа, который возвращается в объекте `AsyncResult` без изменений.

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

void

Примеры

function addSelectionChangedEventHandler() {
    Office.context.document.settings.addHandlerAsync(Office.EventType.SettingsChanged, MyHandler);
}

function MyHandler(eventArgs: Office.SettingsChangedEventArgs) {
    write('Event raised: ' + eventArgs.type);
    doSomethingWithSettings(eventArgs.settings);
}

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

get(name)

Извлекает указанный параметр.

get(name: string): any;

Параметры

name: string

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

any

Объект с именами свойств, сопоставленными с сериализованными значениями JSON.

Примеры

function displayMySetting() {
    write('Current value for mySetting: ' + Office.context.document.settings.get('mySetting'));
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

refreshAsync(callback)

Считывает все параметры, сохраненные в документе, и обновляет копию этих параметров в памяти для контентной надстройки или надстройки области задач.

refreshAsync(callback?: (result: AsyncResult<Office.Settings>) => void): void;

Параметры

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

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

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

void

Этот метод полезен в сценариях совместного редактирования Excel, Word и PowerPoint, когда несколько экземпляров одной надстройки работают с одним документом. Так как каждая надстройка работает с находящейся в памяти копией параметров, загруженных из документа в момент его открытия, значения параметров, используемые каждым пользователем, могут быть рассинхронизированы. Это может произойти каждый раз, Settings.saveAsync когда экземпляр надстройки вызывает метод для сохранения всех параметров этого пользователя в документе. Вызов refreshAsync метода из обработчика событий для settingsChanged события надстройки обновит значения параметров для всех пользователей.

В функции обратного вызова, передаваемой методу refreshAsync , можно использовать свойства AsyncResult объекта для возврата следующих сведений.

Property	Использовать
`AsyncResult.value`	Доступ к объекту `Settings` с обновленными значениями.
`AsyncResult.status`	Определяет, удалось ли выполнить операцию.
`AsyncResult.error`	Получите доступ к объекту `Error` , предоставляющему сведения об ошибке, если операция завершилась сбоем.
`AsyncResult.asyncContext`	Определите элемент любого типа, который возвращается в объекте `AsyncResult` без изменений.

Примеры

function refreshSettings() {
    Office.context.document.settings.refreshAsync(function (asyncResult) {
        write('Settings refreshed with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

remove(name)

Удаляет указанный параметр.

Важно! Имейте в виду, что метод Settings.remove влияет только на копию контейнера свойств параметров в памяти. Чтобы сохранить удаление указанного параметра в документе, в какой-то момент после вызова Settings.remove метода и до закрытия надстройки необходимо вызвать Settings.saveAsync метод.

remove(name: string): void;

Параметры

name: string

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

void

Примеры

function removeMySetting() {
    Office.context.document.settings.remove('mySetting');
}

removeHandlerAsync(eventType, options, callback)

Удаляет обработчик событий.settingsChanged

removeHandlerAsync(eventType: Office.EventType, options?: RemoveHandlerOptions, callback?: (result: AsyncResult<void>) => void): void;

Параметры

eventType: Office.EventType

Указывает тип удаляемого события. Обязательно.

options: Office.RemoveHandlerOptions

Предоставляет параметры для определения того, какой обработчик или обработчики событий удаляются.

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

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

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

void

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

В функции обратного вызова, передаваемой методу removeHandlerAsync , можно использовать свойства AsyncResult объекта для возврата следующих сведений.

Property	Использовать
`AsyncResult.value`	Всегда возвращает `undefined` , так как при настройке форматов нет данных или объектов, которые можно было бы извлечь.
`AsyncResult.status`	Определяет, удалось ли выполнить операцию.
`AsyncResult.error`	Получите доступ к объекту `Error` , предоставляющему сведения об ошибке, если операция завершилась сбоем.
`AsyncResult.asyncContext`	Определите элемент любого типа, который возвращается в объекте `AsyncResult` без изменений.

removeHandlerAsync(eventType, callback)

Удаляет обработчик событий.settingsChanged

removeHandlerAsync(eventType: Office.EventType, callback?: (result: AsyncResult<void>) => void): void;

Параметры

eventType: Office.EventType

Указывает тип удаляемого события. Обязательно.

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

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

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

void

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

В функции обратного вызова, передаваемой методу removeHandlerAsync , можно использовать свойства AsyncResult объекта для возврата следующих сведений.

Property	Использовать
`AsyncResult.value`	Всегда возвращает `undefined` , так как при настройке форматов нет данных или объектов, которые можно было бы извлечь.
`AsyncResult.status`	Определяет, удалось ли выполнить операцию.
`AsyncResult.error`	Получите доступ к объекту `Error` , предоставляющему сведения об ошибке, если операция завершилась сбоем.
`AsyncResult.asyncContext`	Определите элемент любого типа, который возвращается в объекте `AsyncResult` без изменений.

Примеры

function removeSettingsChangedEventHandler() {
    Office.context.document.settings.removeHandlerAsync(Office.EventType.SettingsChanged);
}

saveAsync(options, callback)

Хранится в копии контейнера свойств параметров в документе, содержащейся в памяти.

saveAsync(options?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;

Параметры

options: Office.SaveSettingsOptions

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

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

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

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

void

Параметры, сохраненные надстройкой, загружаются при инициализации, поэтому во время сеанса вы можете использовать методы set и get для работы с копией контейнера свойств в памяти. Если вы хотите сохранить параметры для работы с ними при использовании надстройки в дальнейшем, используйте метод saveAsync.

Примечание. Метод saveAsync сохраняет контейнер свойств параметров в памяти в файле документа. Изменения в самом файле документа сохраняются только в том случае, если пользователь (или параметр автовосстановления) сохраняет документ в файловой системе. Этот refreshAsync метод полезен при совместном редактировании сценариев, когда другие экземпляры той же надстройки могут изменить параметры, и эти изменения должны быть доступны всем экземплярам.

Property	Использовать
`AsyncResult.value`	Всегда возвращается `undefined` , так как нет объекта или данных, которые можно было бы извлечь.
`AsyncResult.status`	Определяет, удалось ли выполнить операцию.
`AsyncResult.error`	Получите доступ к объекту `Error` , предоставляющему сведения об ошибке, если операция завершилась сбоем.
`AsyncResult.asyncContext`	Определите элемент любого типа, который возвращается в объекте `AsyncResult` без изменений.

saveAsync(callback)

Хранится в копии контейнера свойств параметров в документе, содержащейся в памяти.

saveAsync(callback?: (result: AsyncResult<void>) => void): void;

Параметры

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

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

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

void

Параметры, сохраненные надстройкой, загружаются при инициализации, поэтому во время сеанса вы можете использовать методы set и get для работы с копией контейнера свойств в памяти. Если вы хотите сохранить параметры для работы с ними при использовании надстройки в дальнейшем, используйте метод saveAsync.

Примечание. Метод saveAsync сохраняет контейнер свойств параметров в памяти в файле документа. Изменения в самом файле документа сохраняются только в том случае, если пользователь (или параметр автовосстановления) сохраняет документ в файловой системе. Этот refreshAsync метод полезен при совместном редактировании сценариев, когда другие экземпляры той же надстройки могут изменить параметры, и эти изменения должны быть доступны всем экземплярам.

Property	Использовать
`AsyncResult.value`	Всегда возвращается `undefined` , так как нет объекта или данных, которые можно было бы извлечь.
`AsyncResult.status`	Определяет, удалось ли выполнить операцию.
`AsyncResult.error`	Получите доступ к объекту `Error` , предоставляющему сведения об ошибке, если операция завершилась сбоем.
`AsyncResult.asyncContext`	Определите элемент любого типа, который возвращается в объекте `AsyncResult` без изменений.

Примеры

function persistSettings() {
    Office.context.document.settings.saveAsync(function (asyncResult) {
        write('Settings saved with status: ' + asyncResult.status);
    });
}
// Function that writes to a div with id='message' on the page.
function write(message) {
    document.getElementById('message').innerText += message;
}

set(name, value)

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

Важно! Имейте в виду, что метод Settings.set влияет только на копию контейнера свойств параметров в памяти. Чтобы убедиться, что дополнения или изменения параметров будут доступны для вашей надстройки при следующем открытии документа, в какой-то момент после вызова Settings.set метода и до закрытия надстройки, необходимо вызвать Settings.saveAsync метод для сохранения параметров в документе.

set(name: string, value: any): void;

Параметры

name: string

value: any

Задает сохраняемое значение.

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

void

Метод set создает новый параметр с указанным именем, если он еще не существует, или задает существующий параметр с указанным именем в копии контейнера свойств параметров в памяти. После вызова Settings.saveAsync метода значение сохраняется в документе в виде сериализованного JSON-представления его типа данных.

Примеры

function setMySetting() {
    Office.context.document.settings.set('mySetting', 'mySetting value');
}

Комментарии

Используется

Методы

Сведения о методе

addHandlerAsync(eventType, handler, options, callback)

Параметры

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

Комментарии

addHandlerAsync(eventType, handler, callback)

Параметры

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

Комментарии

Примеры

get(name)

Параметры

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

Комментарии

Примеры

refreshAsync(callback)

Параметры

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

Комментарии

Примеры

remove(name)

Параметры

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

Комментарии

Примеры

removeHandlerAsync(eventType, options, callback)

Параметры

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

Комментарии

removeHandlerAsync(eventType, callback)

Параметры

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

Комментарии

Примеры

saveAsync(options, callback)

Параметры

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

Комментарии

saveAsync(callback)

Параметры

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

Комментарии

Примеры

set(name, value)

Параметры

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

Комментарии

Примеры

Обратная связь