Office.RoamingSettings interface

Пакет:

outlook

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

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

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

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

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

Комментарии

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

Важно!

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

• В классической версии Outlook для Windows, если параметры роуминга были настроены в другом клиенте Outlook, перезапускать классический клиент не нужно. Однако для доступа к этим параметрам надстройку необходимо перезагрузить. В Outlook в Интернете, на Mac и в новой версии Outlook для Windows необходимо обновить браузер или перезапустить клиент, чтобы получить доступ к настройкам роуминга, настроенным на другом клиенте.

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

Применимый режим Outlook: Compose или чтение

Используется

• Office.Context: roamingSettings

Методы

get(name)	Извлекает указанный параметр.
remove(name)	Удаляет указанный параметр.
saveAsync(callback)	Сохраняет параметры. Все параметры, ранее сохраненные надстройкой, загружаются при ее инициализации, поэтому в течение жизненного цикла сеанса можно просто использовать методы set and get для работы с копией контейнера свойств settings в памяти. Если вы хотите сохранить параметры, чтобы они были доступны при следующем использовании надстройки, используйте этот saveAsync метод.
set(name, value)	Устанавливает или создает указанный параметр. Метод set создает новый параметр с указанным именем, если его еще нет, или задает существующий параметр с указанным именем. Значение сохраняется в документе как сериализованное представление JSON с его типом данных. Для параметров каждой надстройки доступно не более 32 КБ. При превышении этого ограничения возникает ошибка с кодом 9057. Любые изменения, внесенные в настройки с помощью метода, set не будут сохранены на сервере до тех пор, пока не будет вызван saveAsync метод.

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

get(name)

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

get(name: string): any;

Параметры

name

string

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

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

any

Тип: Строка | Номер | Логическое | Объект | Массив

Комментарии

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

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

Применимый режим Outlook: Compose или чтение

Примеры

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

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

remove(name)

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

remove(name: string): void;

Параметры

name

string

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

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

void

Комментарии

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

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

Применимый режим Outlook: Compose или чтение

Примеры

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

// Remove the specified setting from the mailbox.
const settingName = (document.getElementById("settingName") as HTMLInputElement).value;
Office.context.roamingSettings.remove(settingName);
console.log(`The "${settingName}" setting has been removed.`);

saveAsync(callback)

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

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

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

Параметры

callback

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

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

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

void

Комментарии

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

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

Применимый режим Outlook: Compose или чтение

Примеры

// 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

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

Применимый режим Outlook: Compose или чтение

Примеры

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

const settingName = (document.getElementById("settingName") as HTMLInputElement).value;
const settingValue = (document.getElementById("settingValue") as HTMLInputElement).value;
Office.context.roamingSettings.set(settingName, settingValue);
console.log(`Setting "${settingName}" set to value "${settingValue}".`);