Office.Settings interface

Пакет:: office

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

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

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

Объект 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. Чтобы сохранить удаление указанного параметра в документе, в какой-то момент после вызова `Settings.remove` метода и перед закрытием надстройки `Settings.saveAsync` необходимо вызвать метод .
removeHandlerAsync(eventType, options, callback)	Удаляет обработчик `settingsChanged` события.
removeHandlerAsync(eventType, callback)	Удаляет обработчик `settingsChanged` события.
saveAsync(options, callback)	Хранится в копии контейнера свойств параметров в документе, содержащейся в памяти.
saveAsync(callback)	Хранится в копии контейнера свойств параметров в документе, содержащейся в памяти.
set(name, value)	Устанавливает или создает указанный параметр. Важно! Имейте в `Settings.set` виду, что метод влияет только на копию в памяти контейнера свойств settings. Чтобы убедиться, что добавления или изменения параметров будут доступны вашей надстройке при следующем открытии документа, в какой-то момент после вызова `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 события.

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

Параметры

eventType: Office.EventType

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

handler: any

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

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. Чтобы сохранить удаление указанного параметра в документе, в какой-то момент после вызова 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

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

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

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

void

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

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

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

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

void

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. Чтобы убедиться, что добавления или изменения параметров будут доступны вашей надстройке при следующем открытии документа, в какой-то момент после вызова Settings.set метода и перед закрытием надстройки необходимо вызвать Settings.saveAsync метод для сохранения параметров в документе.

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

Параметры

name: string

value: any

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

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

void

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

Примеры

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

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

Были ли сведения на этой странице полезными?

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

Office.Settings interface

Комментарии

Методы

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

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)

Параметры

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

Комментарии

Примеры

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