Office.Settings interface

  • Ссылка
Пакет:
office

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

Комментарии

Приложения: Excel, PowerPoint, Word

Параметры, созданные с помощью методов объекта 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.

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

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

void

Комментарии

Набор обязательных требований: не в наборе

Можно добавить несколько обработчиков событий для указанного eventType, если имя каждой функции обработчика событий является уникальным.

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.

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

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

void

Комментарии

Набор обязательных требований: не в наборе

Можно добавить несколько обработчиков событий для указанного eventType, если имя каждой функции обработчика событий является уникальным.

Примеры

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 для возврата следующей информации.

Свойство Использовать
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

Комментарии

Набор обязательных требований: Параметры

Для параметра допустимо значение null. Таким образом, назначение параметру значения null не приведет к его удалению из контейнера свойств параметров.

Примеры

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

Комментарии

Набор обязательных требований: не в наборе

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

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

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

Свойство Использовать
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

Комментарии

Набор обязательных требований: не в наборе

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

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

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

Свойство Использовать
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

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

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

void

Комментарии

Набор обязательных требований: Параметры

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

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

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

Свойство Использовать
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');
}