Outlook 外接程序 API

  • 项目

要将 API 用于您的 Outlook 外接程序，您必须指定 Office.js 库的位置、要求集、架构和权限。 你将主要使用通过 Mailbox 对象公开的 Office JavaScript API。

Office.js 库

若要与 Outlook 外接程序 API 交互，需要使用 Office.js 中的 JavaScript API。 库的内容分发网络 (CDN) 为 https://appsforoffice.microsoft.com/lib/1/hosted/Office.js。 提交到 AppSource 的加载项必须按此 CDN 引用 Office.js，它们不能使用本地引用。

在实现加载项 UI 的网页（.html、.aspx 或 .php 文件）的 <head> 标记的 <script> 标记中引用 CDN。

<script src="https://appsforoffice.microsoft.com/lib/1/hosted/Office.js" type="text/javascript"></script>

添加 API 时，Office.js 的 URL 将保持不变。 仅当我们打破现有的 API 行为时，才会更改 URL 中的版本。

重要

为任何 Office 客户端应用程序开发加载项时，请从页面的 部分内 <head> 引用 Office JavaScript API。 这样可确保 API 先于所有正文元素完全初始化。

要求集

所有 Outlook API 都属于 邮箱要求集。 Mailbox 要求集具有多个版本，并且我们发布的每组新的 API 都属于更高版本的要求集。 并非所有的 Outlook 客户端在发布时都将支持最新的 API 集，但如果 Outlook 客户端声明支持要求集，它将支持该要求集中的所有 API。

若要控制外接程序在哪些 Outlook 客户端中显示，请在清单中指定最低要求集版本。 例如，如果你指定要求集版本 1.3，则外接程序不会显示在任何不支持 1.3 及以上版本的 Outlook 客户端中。

指定要求集不会将外接程序限定于该版本中的 API。 如果外接程序指定要求集 v1.1，却在支持 v1.3 的 Outlook 客户端中运行，该外接程序仍可以使用 v1.3 API。 要求集仅控制外接程序在哪些 Outlook 客户端中显示。

要检查大于清单中所指定要求集的要求集中任何 API 的可用性，可以使用标准 JavaScrip：

if (item.somePropertyOrFunction) {
   item.somePropertyOrFunction...  
}

注意

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

指定支持你的方案的关键 API 集的最低要求集，如果缺少该要求集，加载项的功能将无法工作。 在清单中指定要求集。 标记因所使用的清单而异。

  • XML 清单：使用 <Requirements> 元素。 请注意，Outlook 加载项不支持 Requirements> 的<Methods> 子元素，因此无法声明对特定方法的支持。<
  • Microsoft 365 的统一清单：使用“extensions.capabilities”属性。

有关详细信息，请参阅 Office 外接程序清单和 了解 Outlook API 要求集。

权限

外接程序需要相应的权限才能使用所需的 API。 一般情况下，应该指定加载项所需的最小权限。

有四个权限级别： 受限、 读取项目、 读/写项目和 读/写邮箱。 有关更多详细信息。 有关详细信息，请参阅了解 Outlook 外接程序权限。

Mailbox 对象

Outlook 外接程序主要使用通过 Mailbox 对象公开的 API 的子集。 若要访问专门用于 Outlook 加载项的对象和成员（如 Item 对象），请使用 Context 对象的 mailbox 属性来访问 Mailbox 对象，如以下代码行所示。

// Access the Item object.
const item = Office.context.mailbox.item;

此外，Outlook 加载项可以使用以下对象。

  • Office 对象：用于初始化。

  • Context 对象：用于访问内容和显示语言属性。

  • RoamingSettings 对象：用于将 Outlook 加载项专用自定义设置保存到安装了加载项的用户邮箱。

有关在 Outlook 加载项中使用 JavaScript 的信息，请参阅 Outlook 加载项。

另请参阅