Office.Settings interface

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

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

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

Параметры

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

Комментарии

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

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

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

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

addHandlerAsync(eventType: Office.EventType, handler: any, callback?: (result: AsyncResult<void>) => void): 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: 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?: (result: AsyncResult<Office.Settings>) => void): void;

Параметры

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

Комментарии

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

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

Если функция обратного вызова передана методу refreshAsync, можно использовать свойства объекта 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; 
}

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

Важно! Имейте в виду, что метод 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;

Параметры

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

Комментарии

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

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

Примеры

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

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

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

Параметры

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

Комментарии

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

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

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

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

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

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

Параметры

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

Комментарии

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

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

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

В функции обратного вызова, переданной в метод removeHandlerAsync, можно использовать свойства объекта 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?: SaveSettingsOptions, callback?: (result: AsyncResult<void>) => void): void;

Параметры

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

Комментарии

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

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

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

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

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

Параметры

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

Комментарии

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

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

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

Примеры

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; 
}

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

Важно! Имейте в виду, что метод 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;

Параметры

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

Комментарии

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

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

Примеры

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