Outlook JavaScript API 要求集

  • 项目

Outlook 外接程序在其清单中声明所需的 API 版本。 标记因使用的是 XML 清单格式 还是 Microsoft 365 的统一清单而异。

API 版本由“extensions.requirements.capabilities”属性指定。 将“capabilities.name”属性设置为“Mailbox”，将“capabilities.minVersion”属性设置为支持外接程序方案的最低 API 要求集。

例如，下面的清单段表示 1.1 的最低要求集。

"extensions": [
{
  "requirements": {
    "capabilities": [
      {
        "name": "Mailbox", "minVersion": "1.1"
      }
    ]
  },
  ...
}

所有 Outlook API 都属于 Mailbox要求集。 要求集具有不同版本，我们发布的每个新 API 集均属于较高版本的要求集。 并非所有 Outlook 客户端都支持最新的 API 集，但如果 Outlook 客户端声明支持某个要求集，则通常它支持该要求集中的所有 API， (检查 特定 API 或功能的文档) 。

在清单中设置最低要求集版本，控制加载项将在哪个 Outlook 客户端中显示。 如果客户端不支持最低要求集，则不会加载加载项。 例如，如果指定要求集版本 1.3，则意味着外接程序不会显示在任何不支持 1.3 及以上版本的 Outlook 客户端中。

注意

尽管 Android 版和 iOS 版 Outlook 支持的要求集高达 1.5，但移动加载项现在可以实现更高要求集中的一些 API。 有关 Outlook 移动版支持哪些 API 的详细信息，请参阅移动设备 上的 Outlook 中支持的 Outlook JavaScript API。

使用更高要求集中的 API

设置要求集不会限制外接程序可以使用的可用 API。 例如，如果外接程序指定要求集“Mailbox 1.1”，但它在支持“Mailbox 1.3”的 Outlook 客户端中运行，则外接程序可以使用要求集“Mailbox 1.3”中的 API。

若要使用较新的 API，开发人员可执行以下操作来检查特定应用程序是否支持相应的要求集：

if (Office.context.requirements.isSetSupported('Mailbox', '1.3')) {
  // Perform actions.
}
else {
  // Provide alternate flow/logic.
}

或者，开发人员可以使用标准的 JavaScript 技术检查是否存在较新 API。

if (item.somePropertyOrMethod !== undefined) {
  // Use item.somePropertyOrMethod.
  item.somePropertyOrMethod;
}

对于清单中所指定的要求集版本中的任何 API，无需执行此类检查。

选择最低要求集

开发人员应使用包含其方案关键 API 集的最早要求集，如果不使用该要求集，外接程序将不起作用。

Exchange 服务器和 Outlook 客户端支持的要求集

本节将说明 Exchange 服务器和 Outlook 客户端支持的要求集范围。 有关运行 Outlook 加载项的服务器和客户端要求的详细信息，请参阅 Outlook 加载项要求。

重要

如果目标 Exchange 服务器和 Outlook 客户端支持不同的要求集，则可能受限于较低的要求集范围。 例如，如果外接程序在 Windows 上的 Outlook 2019 中运行， (最高要求集：1.6) 针对 Exchange 2016 (最高要求集：1.5) ，则外接程序可能限制为要求集 1.5。

Exchange 服务器支持

下列服务器支持 Outlook 外接程序。

产品 主要 Exchange 版本 受支持的 API 要求集
Exchange Online 最新版本 1.1、 1.2、 1.3、 1.4、 1.5、 1.6、 1.7、 1.8、 1.9、 1.10、 1.11、 1.12、 1.13
IdentityAPI 1.31
Exchange 本地2 2019 1.1、1.2、1.3、1.4、1.5
2016 1.1、1.2、1.3、1.4、1.5

注意

1 若要在 Outlook 外接程序代码中要求标识 API 集 1.3，检查调用 isSetSupported('IdentityAPI', '1.3')是否支持。 声明其在 Outlook 加载项清单中不受支持。 还可通过检查其不是 undefined 来确定该 API 是否受到支持。 有关详细信息，请参阅 从后续要求集中使用 API。

2 即使外接程序从 Exchange 本地环境不支持的要求集中实现功能，只要其清单中指定的要求集与本地 Exchange 支持的要求集一致，它仍然可以添加到 Outlook 客户端。 但是，仅当安装加载项的 Outlook 客户端支持功能所需的最低要求集时，实现的功能才起作用。 若要确定不同 Outlook 客户端支持的要求集，请参阅 Outlook 客户端支持。 对于任何异常，我们建议使用有关特定功能的文档对此进行补充。

Outlook 客户端支持

下列平台上的 Outlook 支持外接程序。

平台 主要 Office/Outlook 版本 受支持的 API 要求集
Web 浏览器1 2 连接到的新式 Outlook UI
Exchange Online：订阅、Outlook.com		 1.1、 1.2、 1.3、 1.4、 1.5、 1.6、 1.7、 1.8、 1.9、 1.10、 1.11、 1.12、 1.13
IdentityAPI 1.33
连接到的经典 Outlook UI
本地 Exchange		 1.1、1.2、1.3、1.4、1.5、1.6
Windows 新的 Windows 版 Outlook (预览版) 1.1、 1.2、 1.3、 1.4、 1.5、 1.6、 1.7、 1.8、 1.9、 1.10、 1.11、 1.12、 1.13
IdentityAPI 1.33
  • Microsoft 365 订阅
  • 零售永久
 1.1、 1.2、 1.3、 1.4、 1.5、 1.6、 1.7、 1.84、 1.94、 1.104、 1.114、 1.124、 1.134
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
批量许可的永久 Outlook 2021 1.1、 1.2、 1.3、 1.4、 1.5、 1.6、 1.7、 1.84、 1.94
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
批量许可永久 Outlook 2019 1.1、1.2、1.3、1.4、1.5、1.6、1.7
批量许可的永久Outlook 2016 1.1、 1.2、 1.3、 1.45
Mac 新 UI6 1.1、 1.2、 1.3、 1.4、 1.5、 1.6、 1.7、 1.8、 1.9、 1.10、 1.11、 1.12、 1.13
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
经典 UI 1.1、1.2、1.3、1.4、1.5、1.6、1.7、1.8
IdentityAPI 1.33
OpenBrowserWindowApi 1.1
Android1 7 8 订阅 1.1、1.2、1.3、1.4、1.5
iOS1 7 8 订阅 1.1、1.2、1.3、1.4、1.5

注意

1 Android 版 Outlook、iOS 版和具有本地 Exchange 帐户的新式移动 Web 不支持加载项。 使用具有经典Outlook 网页版的本地 Exchange 帐户时，某些 iOS 设备仍支持加载项。 有关支持的设备的信息，请参阅运行 Office 加载项的要求。

2 加载项不适用于 iPhone 和 Android 智能手机上的现代Outlook 网页版。 有关支持的设备的信息，请参阅运行 Office 加载项的要求。

3 若要要求在 Outlook 外接程序代码中设置标识 API 1.3，检查调用 isSetSupported('IdentityAPI', '1.3')是否支持。 声明其在 Outlook 加载项清单中不受支持。 还可通过检查其不是 undefined 来确定该 API 是否受到支持。 有关详细信息，请参阅 从后续要求集中使用 API。

4 使用 Microsoft 365 订阅或零售永久许可证在 Outlook on Windows 中对最新要求集的版本支持，如下所示：

  • 版本 1910 (内部版本 12130.20272) 提供对 1.8 的支持。
  • 版本 2008 (内部版本 13127.20296) 提供对 1.9 的支持。
  • 版本 2104 (内部版本 13929.20296) 提供对 1.10 的支持。
  • 版本 2110 (内部版本 14527.20226) 提供对 1.11 的支持。
  • 版本 2206 (内部版本 15330.20196) 提供对 1.12 的支持。
  • 版本 2304 (内部版本 16327.20248) 提供对 1.13 的支持。

有关版本的详细信息，请参阅 Office 2021 或 Microsoft 365 的更新历史记录页，以及如何查找 Office 客户端版本和更新通道。

5 作为 2018 年 7 月 3 日 Office 2016 (KB4022223) 更新的一部分，添加了对批量许可永久Outlook 2016中的 1.4 的支持。

6 Outlook 版本 16.38.506 提供对新 Mac UI 的支持。 有关详细信息，请参阅 全新 Mac UI 上 Outlook 中的加载项支持 部分。

7 目前，在为移动客户端设计和实现加载项时，还有其他注意事项。 有关详细信息，请参阅在 移动设备上在 Outlook 中添加对外接程序命令的支持时的代码注意事项。

8 尽管 Android 版 Outlook 和 iOS 版支持的要求集最高为 1.5，但移动加载项现在可以实现更高要求集中的某些 API。 有关 Outlook 移动版支持哪些 API 的详细信息，请参阅移动设备 上的 Outlook 中支持的 Outlook JavaScript API。

提示

可通过查看邮箱工具栏，在 Web 浏览器中区分经典和新式 Outlook。

新式

新式 Outlook 工具栏。

经典

经典 Outlook 工具栏。

引用 Office JavaScript API 生产库

若要在任何编号的要求集内使用 API，应引用 Office.js 内容分发网络（CDN）上的生产库。 有关如何使用预览 API 的信息，请参阅 测试预览 API。

测试预览 API

新的 Outlook JavaScript API 首先在“预览版”中引入，在进行充分测试并获得用户反馈后，它将成为编号的特定要求集的一部分。 若要提供有关预览 API 的反馈，请使用在其内记录 API 的网页末尾的反馈机制。

注意

预览版 API 可能会发生更改，不适合在生产环境中使用。

有关预览 API 的更多详细信息，请参阅 Outlook API 预览要求集。