Office.RoamingSettings interface

  • 参考
包:
outlook

通过使用 RoamingSettings 对象的方法创建的设置将按外接程序和按用户进行保存。 也就是说，它们仅适用于创建它们的加载项，并且只能从保存它们的用户的邮箱中使用。

虽然 Outlook 外接程序 API 将对这些设置的访问限制为仅创建这些设置的加载项，但这些设置不应被视为安全存储。 可以通过 Exchange Web 服务或扩展 MAPI 访问这些设置。 它们不应用于存储敏感信息，例如用户凭据或安全令牌。

设置的名称是一个字符串，而值可以是字符串、数字、布尔值、null 值、对象或数组。

可通过 RoamingSettings 命名空间中的 roamingSettings 属性访问 Office.context 对象。

若要详细了解 RoamingSettings，请参阅 获取和设置 Outlook 外接程序的外接程序元数据。

注解

[ API set： Mailbox 1.1 ]

重要说明：

  • RoamingSettings仅当首次加载加载项时，才会从持久存储中初始化 对象。 对于任务窗格，这意味着它仅在任务窗格首次打开时初始化。 如果任务窗格导航到另一页或重新加载当前页，则内存中对象会重置为其初始值，即使加载项已保留更改也是如此。 在关闭并重新打开无 UI) 加载项的情况下，任务窗格 (或项之前，保留的更改将不可用。

  • 通过 Windows 或 Mac 上的 Outlook 进行设置和保存时，这些设置仅在浏览器刷新后才会反映在Outlook 网页版中。

最低权限级别： 受限

适用的 Outlook 模式：撰写或阅读

方法

get(name)

检索指定设置。
remove(name)

移除指定设置。
saveAsync(callback)

保存设置。

加载项以前保存的任何设置在初始化时会加载，因此在会话生存期内，只需使用 set 和 get 方法来处理设置属性包的内存中副本。 如果要保留设置，以便下次使用外接程序时可以使用这些设置，请使用 saveAsync 方法。
set(name, value)

设置或创建指定设置。

方法 set 创建指定名称的新设置（如果尚不存在），或设置指定名称的现有设置。 该值在文档中存储为其数据类型的序列化 JSON 表示形式。

每个加载项的设置最多有 32KB 可用。 超过该大小限制时，将引发代码为 9057 的错误。

在调用 方法之前saveAsync，set对使用 方法的设置所做的任何更改都不会保存到服务器。

方法详细信息

get(name)

检索指定设置。

get(name: string): any;

参数

name

string

要检索的设置的区分大小写的名称。

返回

any

类型：字符串|数字|布尔|对象|阵 列

注解

[ API set： Mailbox 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 set： Mailbox 1.1 ]

最低权限级别： 受限

适用的 Outlook 模式：撰写或阅读

saveAsync(callback)

保存设置。

加载项以前保存的任何设置在初始化时会加载，因此在会话生存期内，只需使用 set 和 get 方法来处理设置属性包的内存中副本。 如果要保留设置，以便下次使用外接程序时可以使用这些设置，请使用 saveAsync 方法。

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

参数

callback

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

可选。 方法完成后，使用类型的Office.AsyncResult单个参数调用在 参数中callback传递的函数。

返回

void

注解

[ API set： Mailbox 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 表示形式。

每个加载项的设置最多有 32KB 可用。 超过该大小限制时，将引发代码为 9057 的错误。

在调用 方法之前saveAsync，set对使用 方法的设置所做的任何更改都不会保存到服务器。

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

参数

name

string

要设置或创建的设置的名称（区分大小写）。

value

any

Specifies the value to be stored.

返回

void

注解

[ API set： Mailbox 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}".`);