Outlook JavaScript API 要求集

Outlook 外接程序在其清单中声明所需的 API 版本。 标记因使用的是 Teams 清单格式 (预览) 还是 XML 清单格式而异。

API 版本由 Requirements 元素指定。 Outlook 外接程序始终包括 属性设置为 NameMailbox 属性设置为支持外接程序方案的 API 最低要求集的 MinVersion 元素。

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

<Requirements>
  <Sets>
    <Set Name="Mailbox" MinVersion="1.1" />
  </Sets>
</Requirements>

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

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

注意

若要在任何编号的要求集内使用 API,应引用 Office.js 内容分发网络(CDN)上的生产库。

要了解如何使用预览 API,请参阅本文稍后的使用预览 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.
}

重要

当前存在一个 bug,其中 isSetSupported('Mailbox', '1.3') 错误地针对 Exchange 2013 在 Outlook 网页版中返回 true。 若要详细了解受支持的要求集、Exchange 服务器和 Outlook 客户端组合,请参阅 Exchange 服务器和 Outlook 客户端支持的要求集

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

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

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

选择最低要求集

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

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

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

重要

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

Exchange 服务器支持

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

产品 主要 Exchange 版本 受支持的 API 要求集
Exchange Online 最新版本 1.11.21.31.41.51.61.71.81.91.101.111.12
IdentityAPI 1.3*
本地 Exchange 2019 1.11.21.31.41.5
2016 1.11.21.31.41.5
2013 1.1

注意

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

Outlook 客户端支持

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

平台 主要 Office/Outlook 版本 受支持的 API 要求集
Windows - Microsoft 365 订阅
- 零售永久Outlook 2016及更高版本
1.11.21.31.41.51.61.71.811.911.1011.1111.121
IdentityAPI 1.32
批量许可的永久 Outlook 2021 1.11.21.31.41.51.61.71.811.91
IdentityAPI 1.32
批量许可永久 Outlook 2019 1.11.21.31.41.51.6
批量许可的永久Outlook 2016 1.11.21.31.43
永久 Outlook 2013 1.11.21.331.43
Mac 经典 UI 1.11.21.31.41.51.61.71.8
IdentityAPI 1.32
新 UI4 1.11.21.31.41.51.61.71.81.91.101.111.12
IdentityAPI 1.32
iOS5 6 订阅 1.11.21.31.41.5
Android5 6 订阅 1.11.21.31.41.5
Web 浏览器5 7 连接到的新式 Outlook UI
Exchange Online:订阅、Outlook.com
1.11.21.31.41.51.61.71.81.91.101.111.12
IdentityAPI 1.32
连接到的经典 Outlook UI
本地 Exchange
1.11.21.31.41.51.6

注意

1 使用 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 的支持。

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

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

32015 年 12 月 8 日 Outlook 2013 更新 (KB3114349) 开始在 Outlook 2013 中支持 1.3 版本。 对 Outlook 2013 中的 1.4 版本的支持已作为 2016 年 9 月 13 日 Outlook 2013 更新 (KB3118280) 的一部分添加。 2018 年 7 月 3 日 Office 2016 更新 (KB4022223) 添加了对批量许可永久Outlook 2016中 1.4 的支持

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

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

6 目前,在为移动客户端设计和实现加载项时,还有其他注意事项。 例如,只支持“邮件阅读”模式。 有关更多详细信息,请参阅为 Outlook Mobile 添加加载项命令支持时的代码注意事项

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

提示

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

新式

新式 Outlook 工具栏。

经典

经典 Outlook 工具栏。

使用预览 API

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

注意

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

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