Office.RoamingSettings interface
通过使用 RoamingSettings 对象的方法创建的设置将按外接程序和按用户进行保存。 也就是说，它们仅对创建它们的加载项可用，并且仅从保存它们的用户的邮箱中可用。
虽然 Outlook 加载项 API 将对这些设置的访问权限限制为仅创建它们的加载项，但不应将这些设置视为安全存储。 可以通过 Exchange Web 服务或扩展 MAPI 访问这些设置。 不应将其用于存储敏感信息，例如用户凭据或安全令牌。
设置的名称是一个字符串，而值可以是字符串、数字、布尔值、null 值、对象或数组。
可通过 RoamingSettings 命名空间中的 roamingSettings 属性访问 Office.context 对象。
若要了解有关此文件的 RoamingSettings详细信息，请参阅 获取和设置 Outlook 加载项的加载项元数据。
注解
重要说明：
RoamingSettings仅在首次加载加载项时，才会从永久化存储中初始化对象。 对于任务窗格，这意味着仅在首次打开任务窗格时才会初始化它。 如果任务窗格导航到另一页或重新加载当前页面，则内存中对象将重置为其初始值，即使加载项保留了更改。 在关闭并重新打开无 UI 加载项) 的任务窗格 (或项之前，保留的更改将不可用。在 Windows 上的经典 Outlook 中，如果在另一个 Outlook 客户端上配置了漫游设置，则无需重启桌面客户端。 但是，需要重新加载加载项才能访问这些设置。 在 Outlook 网页版、Mac 和 Windows 上的新 Outlook 中，必须刷新浏览器或重启客户端才能访问在其他客户端上设置的漫游设置。
最低权限级别： 受限
适用的 Outlook 模式：Compose 或 Read
使用方
方法
| get(name) | 检索指定设置。 |
| remove(name) | 移除指定设置。 |
| save |
保存设置。 加载项以前保存的任何设置在初始化时都会加载，因此在会话的生存期内，只需使用 set 和 get 方法即可处理 settings 属性包的内存中副本。 如果要保留设置，以便在下次使用加载项时可用，请使用此 |
| set(name, value) | 设置或创建指定设置。 如果 每个加载项的设置最多可提供 32KB。 超过该大小限制时，将引发代码 9057 的错误。 在调用该 |
方法详细信息
get(name)
检索指定设置。
get(name: string): any;参数
- name
-
string
要检索的设置的区分大小写的名称。
返回
any
类型：字符串 |数字 |Boolean |对象 |数组
注解
最低权限级别： 受限
适用的 Outlook 模式：Compose 或 Read
示例
// 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
注解
最低权限级别： 受限
适用的 Outlook 模式：Compose 或 Read
示例
// 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 和 get 方法即可处理 settings 属性包的内存中副本。 如果要保留设置，以便在下次使用加载项时可用，请使用此 saveAsync 方法。
saveAsync(callback?: (asyncResult: Office.AsyncResult<void>) => void): void;参数
- callback
-
(asyncResult: Office.AsyncResult<void>) => void
可选。 当该方法完成时， callback 将使用类型 Office.AsyncResult为 .
返回
void
注解
最低权限级别： 受限
适用的 Outlook 模式：Compose 或 Read
示例
// 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 表示形式。
每个加载项的设置最多可提供 32KB。 超过该大小限制时，将引发代码 9057 的错误。
在调用该saveAsync方法之前，使用该set方法对设置所做的任何更改都不会保存到服务器中。
set(name: string, value: any): void;参数
- name
-
string
要设置或创建的设置的名称（区分大小写）。
- value
-
any
Specifies the value to be stored.
返回
void
注解
最低权限级别： 受限
适用的 Outlook 模式：Compose 或 Read
示例
// 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}".`);