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 в памяти. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.
removeHandlerAsync(eventType, options, callback)	Удаляет обработчик событий для события settingsChanged.
removeHandlerAsync(eventType, callback)	Удаляет обработчик событий для события settingsChanged.
saveAsync(options, callback)	Хранится в копии контейнера свойств параметров в документе, содержащейся в памяти.
saveAsync(callback)	Хранится в копии контейнера свойств параметров в документе, содержащейся в памяти.
set(name, value)	Устанавливает или создает указанный параметр. Важно! Имейте в виду, что метод Settings.set влияет только на копию контейнера свойств settings в памяти. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

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

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) {
    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 в памяти. To persist the removal of the specified setting in the document, at some point after calling the Settings.remove method and before the add-in is closed, you must call the Settings.saveAsync method.

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, MyHandler);
}

function MyHandler(eventArgs) {
    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; 
}

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 в памяти. To make sure that additions or changes to settings will be available to your add-in the next time the document is opened, at some point after calling the Settings.set method and before the add-in is closed, you must call the Settings.saveAsync method to persist settings in the document.

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)

Параметры

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

Комментарии

Примеры

Дополнительные ресурсы