通过

获取和设置 Outlook 加载项的元数据

  • 项目

使用漫游设置、自定义属性或会话数据管理 Outlook 外接程序中的自定义数据。 这些选项允许访问只有 Outlook 外接程序才能访问的自定义数据，但每种方法都分别存储数据。 也就是说，自定义属性无法访问通过漫游设置存储的数据，反之亦然。

下表概述了在 Outlook 外接程序中管理自定义数据的可用选项。

自定义数据选项 最低要求集 适用对象 说明
漫游设置 1.1 邮箱 管理用户邮箱中的自定义数据。 设置自定义数据的外接程序可以从设置了用户邮箱的其他受支持设备访问该数据。 可以在后续 Outlook 会话中访问存储的数据。
自定义属性 1.1 邮件项目 管理用户邮箱中邮件项目的自定义数据。 设置自定义数据的加载项可以从设置了用户邮箱的受支持设备上的邮件项目访问它。 可以在后续 Outlook 会话中访问存储的数据。
会话数据 1.11 邮件项目 管理用户当前 Outlook 会话中邮件项目的自定义数据。 设置自定义数据的外接程序只能在撰写时从邮件项目访问它。

注意

有关要求集及其支持的客户端的信息，请参阅 Outlook JavaScript API 要求集。

若要详细了解每个自定义数据选项，请选择适用的选项卡。

You can specify data specific to a user's Exchange mailbox using the RoamingSettings object. Examples of such data include the user's personal data and preferences. Your mail add-in can access roaming settings when it roams on any device it's designed to run on (desktop, tablet, or smartphone).

对该数据的更改存储在当前 Outlook 会话的这些设置的内存副本中。 更新后，应显式保存所有漫游设置，以便在用户下次打开加载项时，在同一台或任何其他受支持的设备上使用这些设置。

重要

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

漫游设置格式

RoamingSettings 对象中的数据存储为序列化的 JavaScript 对象表示法 (JSON) 字符串。

下面是 结构的一个示例，假设有三个名为 add-in_setting_name_0、 add-in_setting_name_1和 add-in_setting_name_2的已定义的漫游设置。

{
  "add-in_setting_name_0": "add-in_setting_value_0",
  "add-in_setting_name_1": "add-in_setting_value_1",
  "add-in_setting_name_2": "add-in_setting_value_2"
}

加载漫游设置

邮件加载项通常在 Office.onReady 处理程序中加载漫游设置。 以下 JavaScript 代码示例演示如何加载现有漫游设置并获取两个设置（ customerName 和 customerBalance）的值。

let _mailbox;
let _settings;
let _customerName;
let _customerBalance;

Office.onReady((info) => {
  if (info.host === Office.HostType.Outlook) {
    // Initialize instance variables to access API objects.
    _mailbox = Office.context.mailbox;
    _settings = Office.context.roamingSettings;
    _customerName = _settings.get("customerName");
    _customerBalance = _settings.get("customerBalance");
  }
});

创建或分配漫游设置

继续前面的示例，以下 JavaScript 函数 setAddInSetting演示如何使用 RoamingSettings.set 方法设置名为 cookie 的设置，该设置使用今天的日期。 然后，它通过使用 RoamingSettings.saveAsync 方法将所有漫游设置保存到用户邮箱来保留数据。

如果设置尚不存在，则 set 方法创建设置，并将设置分配给指定的值。 方法 saveAsync 异步保存漫游设置。 此代码示例将回调函数 saveMyAddInSettingsCallback传递给 saveAsync。 异步调用完成后， saveMyAddInSettingsCallback 使用一个参数 asyncResult 调用 。 此参数是一个 AsyncResult 对象，其中包含异步调用的结果和所有详细信息。 可以使用可选的 userContext 参数从异步调用向回调函数传递任何状态信息。

// Set a roaming setting.
function setAddInSetting() {
  _settings.set("cookie", Date());
  // Save roaming settings to the mailbox, so that they'll be available in the next session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

// Callback function after saving custom roaming settings.
function saveMyAddInSettingsCallback(asyncResult) {
  if (asyncResult.status === Office.AsyncResultStatus.Failed) {
    // Handle the failure.
  }
}

删除漫游设置

仍然扩展前面的示例，以下 JavaScript 函数 removeAddInSetting，演示如何使用 RoamingSettings.remove 方法删除 cookie 设置并将所有漫游设置保存到邮箱。

// Remove an add-in setting.
function removeAddInSetting()
{
  _settings.remove("cookie");
  // Save changes to the roaming settings for the mailbox, so that they'll be available in the next Outlook session.
  _settings.saveAsync(saveMyAddInSettingsCallback);
}

尝试Script Lab中的代码示例

若要了解如何创建和管理 RoamingSettings 对象，请获取 Outlook 外接程序Script Lab并试用“使用外接程序设置”示例。 若要了解详细信息，请参阅使用 Script Lab 探索 Office JavaScript API。

另请参阅