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


Office.RoamingSettings interface

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

Хотя API надстройки Outlook ограничивает доступ к этим параметрам только надстройке, которая их создала, эти параметры не должны считаться безопасным хранилищем. К ним можно получить доступ с помощью веб-служб Exchange или расширенного MAPI. Они не должны использоваться для хранения конфиденциальной информации, такой как учетные данные пользователя или маркеры безопасности.

Имя параметра — это String, а значение может быть String, Number, Boolean, null, Object или Array.

К объекту RoamingSettings можно получить доступ с помощью свойства roamingSettings в пространстве имен Office.context.

Дополнительные сведения см RoamingSettings. в статье Получение и настройка метаданных надстройки для надстройки Outlook.

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Важно!

  • Объект RoamingSettings инициализируется из сохраненного хранилища только при первой загрузке надстройки. Для областей задач это означает, что она инициализируется только при первом открытии области задач. Если область задач переходит на другую страницу или перезагружает текущую страницу, объект в памяти сбрасывается до исходных значений, даже если надстройка сохранила изменения. Сохраненные изменения не будут доступны до тех пор, пока область задач (или элемент в случае надстроек без пользовательского интерфейса) не будет закрыта и повторно открыта.

  • При настройке и сохранении в Outlook в Windows (новом или классическом) или на Компьютере Mac эти параметры отражаются в Outlook в Интернете только после обновления браузера.

Минимальный уровень разрешений: ограниченный

Применимый режим Outlook: создание или чтение

Методы

get(name)

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

remove(name)

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

saveAsync(callback)

Сохраняет параметры.

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

set(name, value)

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

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

Для параметров каждой надстройки доступно не более 32 КБ. При превышении этого ограничения по размеру возникает ошибка с кодом 9057.

Любые изменения, внесенные в параметры с помощью set метода , не будут сохранены на сервере saveAsync до вызова метода .

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

get(name)

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

get(name: string): any;

Параметры

name

string

Имя извлекаемого параметра с учетом регистра.

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

any

Тип: String | Число | Boolean | Объект | Массив

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Минимальный уровень разрешений: ограниченный

Применимый режим Outlook: создание или чтение

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = $("#settingName").val();
const settingValue = Office.context.roamingSettings.get(settingName);
$("#settingValue").val(settingValue);
console.log(`The value of setting "${settingName}" is "${settingValue}".`);

remove(name)

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

remove(name: string): void;

Параметры

name

string

Имя удаляемого параметра с учетом регистра

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

void

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Минимальный уровень разрешений: ограниченный

Применимый режим Outlook: создание или чтение

saveAsync(callback)

Сохраняет параметры.

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

saveAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;

Параметры

callback

(asyncResult: Office.AsyncResult<void>) => void

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

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

void

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Минимальный уровень разрешений: ограниченный

Применимый режим Outlook: создание или чтение

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

// Save settings in the mailbox to make it available in future sessions.
Office.context.roamingSettings.saveAsync(function(result) {
  if (result.status !== Office.AsyncResultStatus.Succeeded) {
    console.error(`Action failed with message ${result.error.message}`);
  } else {
    console.log(`Settings saved with status: ${result.status}`);
  }
});

set(name, value)

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

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

Для параметров каждой надстройки доступно не более 32 КБ. При превышении этого ограничения по размеру возникает ошибка с кодом 9057.

Любые изменения, внесенные в параметры с помощью set метода , не будут сохранены на сервере saveAsync до вызова метода .

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

Параметры

name

string

Имя устанавливаемого или создаваемого параметра с учетом регистра.

value

any

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

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

void

Комментарии

[ Набор API: Почтовый ящик 1.1 ]

Минимальный уровень разрешений: ограниченный

Применимый режим Outlook: создание или чтение

Примеры

// Link to full sample: https://raw.githubusercontent.com/OfficeDev/office-js-snippets/prod/samples/outlook/10-roaming-settings/roaming-settings.yaml

const settingName = $("#settingName").val();
const settingValue = $("#settingValue").val();
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);