通过事件激活加载项

基于事件的激活使加载项能够在响应事件时自动启动，因此无需直接用户操作即可验证、插入或刷新关键内容。 该加载项在后台激活以避免中断用户。 还可以将基于事件的激活与任务窗格和函数命令集成。

概述

虽然将基于事件的功能添加到加载项的特定步骤因平台和清单类型而异，但一般流程如下所示。

  1. 更新清单以分配用于处理事件的操作。
  2. 创建 JavaScript 函数，并确保它调用 event.completed 方法。
  3. 使用 Office.actions.associate 方法将函数映射到清单中指定的操作。

尝试基于事件的激活

了解如何通过基于事件的激活简化工作流程并改善用户体验。 试用示例以查看该功能的实际应用。

Outlook 示例

Word 示例

支持的事件

下表列出了当前可用的事件以及每个事件支持的客户端。 引发事件时，处理程序将收到一个 event 对象，其中可能包含特定于事件类型的详细信息。 “ 描述 ”列包括指向相关对象的链接（如果适用）。

Excel、PowerPoint、Word 事件

事件规范名称
和仅加载项清单名称		 Microsoft 365 名称统一清单 说明 支持的客户端和渠道
OnDocumentOpened 尚不支持` 在用户打开文档或创建新文档、电子表格或演示文稿时发生。
  • Office 网页版
  • Windows 版 Office
  • 稍后将提供 Mac 版 Office

有关通过此事件激活的加载项的示例，请参阅 word-add-label-on-open。

提示

通过使用该 OnDocumentOpened 事件，可以在清单中配置加载项，以便在 任何 文档打开时运行代码。 此功能具有 Office 应用程序范围。 Microsoft 365 管理员在 Microsoft 365 租户的管理员门户中安装加载项后，该加载项将在清单中配置该加载项以支持的 Office 应用程序中打开的每个 Office 文档上启动并运行代码。 此功能不同于三个类似功能：

  • 加载项可以以编程方式将自身配置为在文档打开时运行代码。 该技术具有 文档范围，这意味着它必须单独应用于每个文档。 有关详细信息，请参阅 将文档配置为在打开时运行代码。
  • 加载项可以以编程方式将文档配置为在文档打开时自动打开加载项的任务窗格。 此功能还必须单独应用于每个文档。 有关详细信息，请参阅 自动打开包含文档的任务窗格。
  • 可以在清单中配置加载项，以便在最终用户 安装加载项时 打开其任务窗格。 此功能的范围限于 单个文档：安装加载项时打开的文档。 有关详细信息，请参阅 安装加载项时自动打开任务窗格。

Outlook 事件

要求 集 1.10 中引入了对 Outlook 中此功能的支持，后续要求集中现在提供了其他事件。 下表列出了每个事件的最低要求集以及支持它的客户端和平台。 有关 Outlook 客户端及其支持的要求集的详细信息，请参阅 Exchange 服务器和 Outlook 客户端支持的要求集。

事件规范名称
和仅加载项清单名称		 Microsoft 365 名称统一清单 说明 最低要求集和支持的客户端
OnNewMessageCompose newMessageComposeCreated 撰写新邮件时 (包括回复、全部答复和转发) ，但不包括编辑（例如草稿）。 1.10
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
  • Android23
  • iOS23
OnNewAppointmentOrganizer newAppointmentOrganizerCreated 在创建新约会时，而不是在编辑现有约会时。 1.10
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnMessageAttachmentsChanged messageAttachmentsChanged 关于在撰写邮件时添加或删除附件。

特定于事件的数据对象： AttachmentsChangedEventArgs		 1.11
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnAppointmentAttachmentsChanged appointmentAttachmentsChanged 关于在撰写约会时添加或删除附件。

特定于事件的数据对象： AttachmentsChangedEventArgs		 1.11
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnMessageRecipientsChanged messageRecipientsChanged 关于在撰写邮件时添加或删除收件人。

特定于事件的数据对象： RecipientsChangedEventArgs		 1.11
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
  • Android23
  • iOS23
OnAppointmentAttendeesChanged appointmentAttendeesChanged 关于在撰写约会时添加或删除与会者。

特定于事件的数据对象： RecipientsChangedEventArgs		 1.11
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnAppointmentTimeChanged appointmentTimeChanged 在撰写约会时更改日期/时间时。

特定于事件的数据对象： AppointmentTimeChangedEventArgs

【重要事项】如果您将约会拖放到日历上的其他日期/时间段，则不会发生事件 OnAppointmentTimeChanged 。 仅当从约会直接更改日期/时间时时，才会发生这种情况。		 1.11
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnAppointmentRecurrenceChanged appointmentRecurrenceChanged 在撰写约会时添加、更改或删除重复周期详细信息。 如果更改日期/时间，也会发生此 OnAppointmentTimeChanged 事件。

特定于事件的数据对象： RecurrenceChangedEventArgs		 1.11
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnInfoBarDismissClicked infoBarDismissClicked 在撰写邮件或约会项目时关闭通知。 只会通知已添加通知的加载项。

特定于事件的数据对象： InfobarClickedEventArgs		 1.11
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnMessageSend messageSending 发送消息项时。 若要了解详细信息，请尝试 智能警报演练。 1.12
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnAppointmentSend appointmentSending 发送约会项目时。 若要了解详细信息，请参阅 使用智能警报处理 Outlook 加载项中的 OnMessageSend 和 OnAppointmentSend 事件。 1.12
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnMessageCompose messageComposeOpened 撰写新邮件时， (包括回复、全部回复、转发) 或编辑草稿。 1.12
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnAppointmentOrganizer appointmentOrganizerOpened 创建新约会或编辑现有约会时。 1.12
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnMessageFromChanged messageFromChanged 在正在撰写的邮件的 “发件人 ”字段中更改邮件帐户时。 若要了解详细信息，请参阅 在 Exchange 帐户之间切换时自动更新签名。 1.13
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
  • Android23
  • iOS23
OnAppointmentFromChanged appointmentFromChanged 在正在撰写的约会的组织者字段中更改邮件帐户。 若要了解详细信息，请参阅 在 Exchange 帐户之间切换时自动更新签名。 1.13
  • 新 Mac UI2
OnSensitivityLabelChanged sensitivityLabelChanged 关于在撰写邮件或约会时更改敏感度标签。 若要了解如何管理邮件项目的敏感度标签，请参阅 在撰写模式下管理邮件或约会的敏感度标签。

特定于事件的数据对象： SensitivityLabelChangedEventArgs		 1.13
  • Web 浏览器
  • Windows (新版 和经典版1)
  • 新 Mac UI2
OnMessageReadWithCustomAttachment 不可用 在阅读模式下打开包含特定附件类型的邮件时。 预览版4
  • Windows (经典版1)
OnMessageReadWithCustomHeader 不可用 在读取模式下打开包含特定 Internet 标头名称的邮件时。 预览版4
  • Windows (经典版1)
OnMessageDecrypt messageDecrypt 将加密邮件的标头与加载项清单中的标头密钥进行匹配时。 若要了解详细信息，请参阅 创建加密 Outlook 加载项。 1.16
  • Web 浏览器
  • Windows (新版 和经典版1)

注意

1 Windows 上的经典 Outlook 中基于事件的加载项至少需要 Windows 10 版本 1903 (内部版本 18362) 或 Windows Server 2019 版本 1903 才能运行。

2 Mac 上的 Outlook 和移动设备不支持使用 Microsoft 365 统一清单的加载项。 若要使加载项在 Mac 和移动平台上可用，必须创建使用仅加载项清单的第二个版本。 有关更多信息，请参阅包含 Microsoft 365 统一应用清单的 Office 加载项的“客户端和平台支持”部分。

3 有关详细信息，请参阅 在 Outlook 移动加载项中实现基于事件的激活。

4 若要预览 OnMessageReadWithCustomAttachment and OnMessageReadWithCustomHeader 事件，必须安装 Windows 上的经典 Outlook 版本 2312 (内部版本 17110.10000) 或更高版本。 然后，加入 Microsoft 365 预览体验计划 并选择 Beta 版频道 选项以访问 Office Beta 版本。

移动设备上的 Outlook 中基于事件的激活

Outlook 移动版支持的 API 最高可达邮箱要求集 1.5。 但是，现在已启用对更高要求集中引入的其他 API 和功能的支持，例如 OnNewMessageCompose 事件。 若要了解详细信息，请参阅 在 Outlook 移动加载项中实现基于事件的激活。

行为和限制

开发基于事件的加载项时，请注意以下功能行为和限制。

  • 基于事件的加载项仅在由管理员部署时有效。 如果用户直接从 Microsoft Marketplace 或 Office Store 安装它们，则不会自动启动 (以解决 Microsoft Marketplace 限制，请参阅基于 事件的加载项) 的Microsoft市场列表选项 。 管理员部署是通过将清单上传到 Microsoft 365 管理中心来完成的。

  • Word、PowerPoint 和 Excel 不支持与 UI 或显示 UI 元素交互的 API。 这是因为事件处理程序在仅 JavaScript 运行时中运行。 有关详细信息，请参阅 Office 加载项中的运行时。

  • 基于事件的加载项需要 Internet 连接才能在发生特定事件时启动。 加载项事件处理程序应为运行时间短、轻型且尽可能无侵略性的。 激活后，加载项将在大约 300 秒内超时，这是运行基于事件的加载项允许的最大时间长度。要表示加载项已完成处理启动事件，关联的事件处理程序必须调用 Event.Completed 方法。 (请注意，语句后 event.completed 面包含的代码并不保证能够运行。) 每次触发加载项处理的事件时，加载项将重新激活并运行关联的事件处理程序，同时会重置超时窗口。 加载项在超时后结束，或者用户关闭了撰写窗口或发送了项目。

  • 订阅同一事件的多个加载项的行为不是不确定的。 Outlook 启动加载项没有特定顺序。 对于 Excel、PowerPoint 和 Word，只会激活一个随机加载项。 例如，如果多个处理 OnDocumentOpenedWord 加载项，则只会运行其中一个处理程序。

  • 目前，只有五个基于事件的加载项可以主动运行。

  • 在所有受支持的 Outlook 客户端中，用户必须留在激活加载项的当前邮件项上才能完成运行。 离开当前项 (例如，切换到另一个撰写窗口或选项卡) 会终止加载项操作。 但是，在事件上 OnMessageSend 激活的加载项处理方式不同，具体取决于其所运行的 Outlook 客户端。 若要了解详细信息，请参阅使用 智能警报处理 Outlook 加载项中的 OnMessageSend 和 OnAppointmentSend 事件的“用户离开当前邮件”部分。

  • 除了项目切换外，基于事件的加载项也会在用户发送他们正在撰写的消息或约会时停止操作。

Windows 上的 Excel、PowerPoint、Word 和经典 Outlook 中基于事件的加载项限制

开发要在 Windows 客户端上运行的基于事件的加载项时，请注意以下事项：

  • 在其中实现基于事件的激活处理的 JavaScript 文件中不支持导入。

  • 对于基于事件的激活，仅支持清单中引用的 JavaScript 文件。 必须将事件处理 JavaScript 代码捆绑到此单个文件中。 引用的 JavaScript 文件在清单中的位置因加载项使用的清单类型而异。

    • 仅加载项清单： <Override> 节点的 <Runtime> 子元素
    • Microsoft 365 统一清单： "script" 对象的 "code" 属性

    请注意，大型 JavaScript 捆绑包可能会导致加载项性能出现问题。 建议对繁重操作进行预处理，以便在事件处理代码中不包含这些操作。

  • 当清单中指定用于处理事件的 JavaScript 函数运行时，代码输入 Office.onReady() 但 Office.initialize 不运行。 建议改为将事件处理程序添加事件处理程序所需的任何启动逻辑（例如检查用户的客户端版本）。

  • 在 Outlook 中撰写由 回邮链接 (mailto 链接) 启动的邮件时，从事件处理程序中的 OnNewMessageCompose “收件人”、“抄送”或“密件抄送”字段检索收件人可能会返回空数组。 如果在事件发生时 OnNewMessageCompose Outlook 尚未完成对收件人电子邮件地址的解析，则会发生这种情况。 若要解决此问题，请改为在事件处理程序中OnMessageRecipientsChanged检查收件人。

Excel、PowerPoint 和 Word 中基于事件的加载项限制

尚不支持以下平台或功能。

  • Mac 版 Office

Outlook 网页版和新版 Outlook on Windows 中基于事件的加载项限制

在 Outlook 网页版和新版 Outlook on Windows 中，仅在标准读取和撰写邮件及约会界面上支持基于事件的激活。 在某些非标准图面上撰写时，基于事件的激活可能不起作用。 例如：

  • 使用 带注释的 RSVP 选项响应会议邀请。
  • 从日历转发会议。

不支持的 API

某些更改或更改 UI 的 Office.js API 在基于事件的加载项的事件处理程序中是不允许的。下面是阻止的 API。

API 方法
Office.devicePermission
  • requestPermissionsAsync
Office.context.auth*
  • getAccessToken
  • getAccessTokenAsync
Office.context.mailbox
  • displayAppointmentForm
  • displayMessageForm
  • displayNewAppointmentForm
  • displayNewMessageForm
Office.context.mailbox.item
  • close
Office.context.ui
  • displayDialogAsync
  • messageParent

注意

* OfficeRuntime.auth 在支持基于事件的激活和单一登录 (SSO) 的所有版本中均受支持，而 Office.auth 仅在某些 Outlook 版本中受支持。 有关详细信息，请参阅在 基于事件或垃圾邮件报告的 Outlook 加载项中使用单一登录 (SSO) 或跨源资源共享 (CORS) 。

在 Windows) 上的经典 Outlook (事件处理程序中的预览功能

Windows 上的经典 Outlook 包括 Office.js 生产版和 beta 版的本地副本，而不是从内容分发网络加载 (CDN) 。 默认情况下，引用 API 的本地生产副本。 若要引用 API 的本地 beta 版副本，必须配置计算机的注册表。 这将使你能够在经典 Outlook on Windows 中测试事件处理程序中的 预览功能 。

  1. 在注册表中，导航到 HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer。 如果密钥不存在，请创建它。

  2. 创建一个名为的 EnableBetaAPIsInJavaScript 条目，并将其值设置为 1。

    EnableBetaAPIsInJavaScript 注册表值设置为 1。

启用单一登录 (SSO)

若要在基于事件的加载项中启用 SSO，必须将其 JavaScript 文件添加到已知的 URI。 有关如何配置此资源的指导，请参阅在 基于事件或垃圾邮件报告的 Office 加载项中使用单一登录 (SSO) 或跨源资源共享 (CORS) 。

请求外部数据

可以使用 Fetch 等 API 或使用 XHR) (XMLHttpRequest 请求外部数据，XHR 是一种发出 HTTP 请求以与服务器交互的标准 Web API。

注意

如果加载项将在仅限 JavaScript 的运行时中运行，请在 Fetch API 调用中使用绝对 URL。 仅 JavaScript 运行时不支持 Fetch API 调用中的相对 URL。

请注意，使用 XMLHttpRequest 对象时必须使用额外的安全措施，需要 同源策略 和 CORS (跨源资源共享) 。

注意

从版本 2201 内部版本 16.0.14813.10000) 客户端开始，Office web 版、Mac 和 Windows (提供完整的 CORS 支持。

若要从基于事件的加载项发出 CORS 请求，必须将加载项及其 JavaScript 文件添加到已知的 URI。 有关如何配置此资源的指导，请参阅在 基于事件或垃圾邮件报告的 Office 加载项中使用单一登录 (SSO) 或跨源资源共享 (CORS) 。

加载项疑难解答

开发基于事件的加载项时，可能需要排查问题，例如加载项未加载或事件未发生。 有关如何排除基于事件的加载项故障的指南，请参阅 排除基于事件的加载项和垃圾邮件报告加载项故障。

部署加载项

根据 Office 应用程序，可以通过以下选项之一部署基于事件的加载项。

  • 管理员管理的部署：加载项通过 Microsoft 365 管理中心部署。
  • Microsoft Marketplace 上的受限列表：加载项已发布到 Microsoft Marketplace，但不显示在搜索结果中。 加载项获取需要外部测试版代码 URL。 加载项仍必须由管理员部署，基于事件的激活功能才能正常工作。
  • Microsoft Marketplace 上的无限制列表：加载项发布到 Microsoft Marketplace，用户和管理员可以使用加载项的名称或 ID 搜索加载项。 基于事件的激活功能正常工作不需要管理员部署。 加载项必须满足无限制列表的特定要求。

下表概述了按 Office 应用程序进行的基于事件的激活的部署选项。

Office 应用程序 管理员管理的部署 Microsoft 卖场
Excel 支持 受限列表选项
Outlook 支持 受限和无限制列表选项
PowerPoint 支持 受限列表选项
Word 支持 受限列表选项

有关如何通过 Microsoft 365 管理中心部署加载项的说明，请参阅 管理员管理的部署。 若要详细了解如何在 Microsoft Marketplace 中列出基于事件的加载项，请参阅基于 事件的加载项的 Microsoft Marketplace 一览选项。

重要

只有当清单的发送模式属性设置为提示用户或软阻止选项时，使用智能警报功能的加载项才能发布到 Microsoft Marketplace。 如果加载项的发送模式属性设置为 阻止，则它只能由组织的管理员部署，因为它将无法通过 Microsoft 市场验证。

管理员管理的部署

管理员部署是通过将清单上传到 Microsoft 365 管理中心来完成的。 为此，请执行以下步骤。

  1. 在管理门户中，展开导航窗格中的“ 设置 ”部分，然后选择 “集成应用”。

  2. 在 集成应用程序 页面上，选择 上传自定义应用程序 操作。

  3. 后续步骤取决于使用的清单。

    • Microsoft 365 统一清单：

      1. 在 “应用类型 ”下拉框中，选择“ Teams 应用”。 不是Office 加载项！
      2. 使用文件选择器控件导航到并选择应用包 zip 文件。
      3. 按照页面上的说明完成安装。

    • 仅加载项清单：

      1. 在 “应用类型 ”下拉框中，选择“ Office 加载项”。
      2. 使用文件选择器控件导航到并选择清单。
      3. 按照页面上的说明完成安装。

Microsoft 365 管理中心上的“集成应用”页，其中突出显示了“上传自定义应用”操作。

有关如何部署加载项的详细信息，请参阅在 Microsoft 365 管理中心部署和发布 Office 加载项。

部署清单更新

如果基于事件的加载项是由管理员部署的，则对清单进行的任何更改都需要通过 Microsoft 365 管理中心征得管理员同意。 在管理员接受更改之前，组织中的用户将被阻止使用加载项。 若要了解有关管理员同意过程的详细信息，请参阅安装基于事件的加载项的管理员同意。

另请参阅

  • Last updated on