Outlook JavaScript API 要求集Outlook JavaScript API requirement sets

Outlook 外接程序通过在其清单中使用 Requirements 元素来声明所需要的 API 版本。Outlook 外接程序始终包括 属性设置为 和 属性设置为支持外接程序方案的 API 最低要求集的 Set 元素。Outlook add-ins declare what API versions they require by using the Requirements element in their manifest. Outlook add-ins always include a Set element with a Name attribute set to Mailbox and a MinVersion attribute set to the minimum API requirement set that supports the add-in's scenarios.

例如,下面的清单段表示 1.1 的最低要求集。For example, the following manifest snippet indicates a minimum requirement set of 1.1.

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

所有 Outlook API 均属于Mailbox要求集Mailbox要求集具有不同版本,我们发布的每个新 API 集均属于较高版本的要求集。并非所有 Outlook 客户端都支持最新的 API 集,但如果某个 Outlook 客户端声明支持某个要求集,它通常支持该需求集中的所有 API(请查看有关特定 API 或功能的文档以了解任何异常)。All Outlook APIs belong to the Mailbox requirement set. The Mailbox requirement set has versions, and each new set of APIs that we release belongs to a higher version of the set. Not all Outlook clients support the newest set of APIs, but if an Outlook client declares support for a requirement set, generally it supports all of the APIs in that requirement set (check the documentation on a specific API or feature for any exceptions).

在清单中设置最低要求集版本可控制外接程序会显示在哪个 Outlook 客户端中。如果客户端不支持最低要求集,则不会加载外接程序。例如,如果指定要求集版本 1.3,则意味着外接程序不会显示在任何不支持 1.3 及以上版本的 Outlook 客户端中。Setting a minimum requirement set version in the manifest controls which Outlook client the add-in will appear in. If a client does not support the minimum requirement set, it does not load the add-in. For example, if requirement set version 1.3 is specified, this means the add-in will not show up in any Outlook client that doesn't support at least 1.3.

备注

要在任何带编号的要求集中使用 API,应引用 CDN 上的生产库:https://appsforoffice.microsoft.com/lib/1/hosted/office.js)。To use APIs in any of the numbered requirement sets, you should reference the production library on the CDN (https://appsforoffice.microsoft.com/lib/1/hosted/office.js).

要了解如何使用预览 API,请参阅本文稍后的使用预览 API 部分。For information about using preview APIs, see the Using preview APIs section later in this article.

使用更高版本要求集中的 APIUsing APIs from later requirement sets

设置要求集不会限制外接程序可使用的可用 API。Setting a requirement set does not limit the available APIs that the add-in can use. 例如,如果加载项指定要求集“Mailbox 1.1”,但它在支持版本“Mailbox 1.3”的 Outlook 客户端中运行,则该加载项从要求集“Mailbox 1.3”使用 API。For example, if the add-in specifies requirement set "Mailbox 1.1", but it is running in an Outlook client which supports "Mailbox 1.3", the add-in can use APIs from requirement set "Mailbox 1.3".

要使用较新的 API,开发人员可执行以下操作来检查特定主机是否支持相应的要求集。To use a newer API, developers can check if a particular host supports the requirement set by doing the following.

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

或者,开发人员可以使用标准的 JavaScript 技术检查是否存在较新 API。Alternatively, developers can check for the existence of a newer API by using standard JavaScript technique.

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

对于清单中所指定的要求集版本中的任何 API,无需执行此类检查。No such checks are necessary for any APIs which are present in the requirement set version specified in the manifest.

选择最低要求集Choosing a minimum requirement set

开发人员应使用包含其方案关键 API 集的最早要求集,如果不使用该要求集,外接程序将不起作用。Developers should use the earliest requirement set that contains the critical set of APIs for their scenario, without which the add-in won't work.

Exchange 服务器和 Outlook 客户端支持的要求集Requirement sets supported by Exchange servers and Outlook clients

本节将说明 Exchange 服务器和 Outlook 客户端支持的要求集范围。In this section, we note the range of requirement sets supported by Exchange server and Outlook clients. 有关运行 Outlook 加载项的服务器和客户端要求的详细信息,请参阅 Outlook 加载项要求For details about server and client requirements for running Outlook add-ins, see Outlook add-ins requirements.

重要

如果目标 Exchange 服务器和 Outlook 客户端支持不同的要求集,则将受限于较低的要求集范围。If your target Exchange server and Outlook client support different requirement sets, then you're restricted to the lower requirement set range. 例如,如果外接程序在 Mac 上的 Outlook 2016(最高要求集:1.6)中针对 Exchange 2013(最高要求集:1.1)运行,则外接程序受限于要求集 1.1。For example, if an add-in is running in Outlook 2016 on Mac (highest requirement set: 1.6) against Exchange 2013 (highest requirement set: 1.1), your add-in is limited to requirement set 1.1.

Exchange 服务器支持Exchange server support

下列服务器支持 Outlook 外接程序。The following servers support Outlook add-ins.

产品Product 主要 Exchange 版本Major Exchange version 受支持的 API 要求集Supported API requirement sets
Exchange OnlineExchange Online 最新版本Latest build 1.11.21.31.41.51.61.71.81.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
本地 ExchangeExchange on-premises 20192019 1.11.21.31.41.51.1, 1.2, 1.3, 1.4, 1.5
20162016 1.11.21.31.41.51.1, 1.2, 1.3, 1.4, 1.5
20132013 1.11.1

Outlook 客户端支持Outlook client support

下列平台上的 Outlook 支持外接程序。Add-ins are supported in Outlook on the following platforms.

平台Platform 主要 Office/Outlook 版本Major Office/Outlook version 受支持的 API 要求集Supported API requirement sets
WindowsWindows Microsoft 365 订阅Microsoft 365 subscription 1.11.21.31.41.51.61.71.811.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81
2019 一次性购买(零售)2019 one-time purchase (retail) 1.11.21.31.41.51.61.71.811.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.81
2019 一次性购买(批量许可)2019 one-time purchase (volume-licensed) 1.11.21.31.41.51.61.71.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7
2016 一次性购买2016 one-time purchase 1.11.21.31.421.1, 1.2, 1.3, 1.42
2013 一次性购买2013 one-time purchase 1.11.21.321.421.1, 1.2, 1.32, 1.42
MacMac Microsoft 365 订阅Microsoft 365 subscription 1.11.21.31.41.51.61.71.81.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
2019 一次性购买2019 one-time purchase 1.11.21.31.41.51.61.1, 1.2, 1.3, 1.4, 1.5, 1.6
2016 一次性购买2016 one-time purchase 1.11.21.31.41.51.61.1, 1.2, 1.3, 1.4, 1.5, 1.6
iOSiOS Microsoft 365 订阅Microsoft 365 subscription 1.11.21.31.41.531.1, 1.2, 1.3, 1.4, 1.53
AndroidAndroid Microsoft 365 订阅Microsoft 365 subscription 1.1, 1.2, 1.3, 1.4, 1.531.1, 1.2, 1.3, 1.4, 1.53
Web 浏览器Web browser 连接到的新式 Outlook UImodern Outlook UI when connected to
Exchange Online:Microsoft 365 订阅、Outlook.comExchange Online: Microsoft 365 subscription, Outlook.com
1.11.21.31.41.51.61.71.81.1, 1.2, 1.3, 1.4, 1.5, 1.6, 1.7, 1.8
连接到的经典 Outlook UIclassic Outlook UI when connected to
本地 ExchangeExchange on-premises
1.11.21.31.41.51.61.1, 1.2, 1.3, 1.4, 1.5, 1.6

备注

1自版本 1910(生成号 12130.20272)起,包含 Microsoft 365 订阅或零售一次性购买的 Outlook on Windows 开始支持 1.8。1 Support for 1.8 in Outlook on Windows with a Microsoft 365 subscription or a retail one-time purchase is available from version 1910 (build 12130.20272). 如需了解你的版本的更多详情,请参阅 Office 2019Microsoft 365 的更新历史记录页,以及如何查找 Office 客户端版本和更新通道For more details according to your version, see the update history page for Office 2019 or Microsoft 365 and how to find your Office client version and update channel.

22015 年 12 月 8 日 Outlook 2013 更新 (KB3114349) 开始在 Outlook 2013 中支持 1.3 版本。2 Support for 1.3 in Outlook 2013 was added as part of the December 8, 2015, update for Outlook 2013 (KB3114349). 对 Outlook 2013 中的 1.4 版本的支持已作为 2016 年 9 月 13 日 Outlook 2013 更新 (KB3118280) 的一部分添加。Support for 1.4 in Outlook 2013 was added as part of the September 13, 2016, update for Outlook 2013 (KB3118280). 对 Outlook 2016(一次性购买)中的 1.4 版本的支持已作为 2018 年 7 月 3 日 Office 2016 更新 (KB4022223) 的一部分添加。Support for 1.4 in Outlook 2016 (one-time purchase) was added as part of the July 3, 2018, update for Office 2016 (KB4022223).

3 目前,设计和实现移动客户端的加载项时有其他注意事项。3 Currently, there are additional considerations when designing and implementing add-ins for mobile clients. 例如,只支持“邮件阅读”模式。For example, the only supported mode is Message Read. 有关更多详细信息,请参阅为 Outlook Mobile 添加加载项命令支持时的代码注意事项For more details, see code considerations when adding support for add-in commands for Outlook Mobile.

提示

可通过查看邮箱工具栏,在 Web 浏览器中区分经典和新式 Outlook。You can distinguish between classic and modern Outlook in a web browser by checking your mailbox toolbar.

新式modern

新式 Outlook 工具栏的部分屏幕截图

经典classic

经典 Outlook 工具栏的部分屏幕截图

使用预览 APIUsing preview APIs

新的 Outlook JavaScript API 首先在“预览版”中引入,在进行充分测试并获得用户反馈后,它将成为编号的特定要求集的一部分。New Outlook JavaScript APIs are first introduced in "preview" and later become part of a specific, numbered requirement set after sufficient testing occurs and user feedback is acquired. 若要提供有关预览 API 的反馈,请使用在其内记录 API 的网页末尾的反馈机制。To provide feedback about a preview API, please use the feedback mechanism at the end of the web page where the API is documented.

备注

预览 API 可能会发生变更,不适合在生产环境中使用。Preview APIs are subject to change and are not intended for use in a production environment.

有关预览 API 的更多详细信息,请参阅 Outlook API 预览要求集For more details about the preview APIs, see Outlook API Preview requirement set.