为基于事件的激活配置 Outlook 加载项

项目
12/05/2023

如果没有基于事件的激活功能，用户必须显式启动加载项才能完成任务。此功能使外接程序能够基于特定事件运行任务，尤其是适用于每个项的操作。还可以与任务窗格和函数命令集成。

在本演练结束时，你将有一个加载项，每当创建新项目并设置主题时，该加载项就会运行。

注意

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

以下演练中的加载项仅在 Outlook on Windows、Mac 和 Web 上运行。若要了解如何在移动设备上实现在 Outlook 中运行的基于事件的加载项，请参阅在 Outlook 移动加载项中实现基于事件的激活。

支持的事件

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

事件规范名称和 XML 清单名称	Microsoft 365 名称的统一清单	说明	最低要求集和支持的客户端
`OnNewMessageCompose`	newMessageComposeCreated	撰写新邮件 (包括答复、全部答复和转发) 但不在编辑时，例如草稿。	1.10 - Windows¹ - Web 浏览器 - 新建 Mac UI - Android²
`OnNewAppointmentOrganizer`	newAppointmentOrganizerCreated	创建新约会时，但不在编辑现有约会时。	1.10 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnMessageAttachmentsChanged`	messageAttachmentsChanged	在撰写邮件时添加或删除附件。特定于事件的数据对象： AttachmentsChangedEventArgs	1.11 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnAppointmentAttachmentsChanged`	appointmentAttachmentsChanged	在撰写约会时添加或删除附件。特定于事件的数据对象： AttachmentsChangedEventArgs	1.11 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnMessageRecipientsChanged`	messageRecipientsChanged	在撰写邮件时添加或删除收件人。特定于事件的数据对象： RecipientsChangedEventArgs	1.11 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnAppointmentAttendeesChanged`	appointmentAttendeesChanged	在撰写约会时添加或删除与会者。特定于事件的数据对象： RecipientsChangedEventArgs	1.11 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnAppointmentTimeChanged`	appointmentTimeChanged	撰写约会时更改日期/时间。特定于事件的数据对象： AppointmentTimeChangedEventArgs 重要提示：如果将约会拖放到日历上的其他日期/时间段，则不会发生该 `OnAppointmentTimeChanged` 事件。仅当直接从约会更改日期/时间时，才会发生此情况。	1.11 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnAppointmentRecurrenceChanged`	appointmentRecurrenceChanged	在撰写约会时添加、更改或删除定期详细信息。如果更改了日期/时间，也会发生该 `OnAppointmentTimeChanged` 事件。特定于事件的数据对象： RecurrenceChangedEventArgs	1.11 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnInfoBarDismissClicked`	infoBarDismissClicked	撰写邮件或约会项目时关闭通知时。只有添加通知的加载项才会收到通知。特定于事件的数据对象： InfobarClickedEventArgs	1.11 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnMessageSend`	messageSending	发送消息项时。若要了解详细信息，请尝试智能警报演练。	1.12 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnAppointmentSend`	appointmentSending	发送约会项目时。若要了解详细信息，请参阅使用智能警报处理 Outlook 外接程序中的 OnMessageSend 和 OnAppointmentSend 事件。	1.12 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnMessageCompose`	messageComposeOpened	撰写新邮件 (包括答复、全部答复和转发) 或编辑草稿。	1.12 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnAppointmentOrganizer`	appointmentOrganizerOpened	创建新约会或编辑现有约会时。	1.12 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnMessageFromChanged`	不可用	更改正在撰写的邮件的“ 发件人 ”字段中的邮件帐户时。若要了解详细信息，请参阅在 Exchange 帐户之间切换时自动更新签名。	1.13 - Windows¹ - Web 浏览器 - 新建 Mac UI
`OnAppointmentFromChanged`	不可用	更改正在撰写的约会的组织者字段中的邮件帐户时。若要了解详细信息，请参阅在 Exchange 帐户之间切换时自动更新签名。	1.13 - Web 浏览器 - 新建 Mac UI
`OnSensitivityLabelChanged`	不可用	撰写邮件或约会时更改敏感度标签时。若要了解如何管理邮件项目的敏感度标签，请参阅在撰写模式下管理邮件或约会的敏感度标签。特定于事件的数据对象： SensitivityLabelChangedEventArgs	1.13 - Windows¹ - Web 浏览器 - 新建 Mac UI

注意

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

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

设置环境

完成 Outlook 快速入门，该快速入门使用 Office 加载项的 Yeoman 生成器创建外接程序项目。

配置清单

若要配置清单，请选择要使用的清单类型的选项卡。

XML 清单
Microsoft 365 (开发人员预览版的统一清单)

若要启用外接程序的基于事件的激活，必须在清单的节点中VersionOverridesV1_1配置 Runtimes 元素和 LaunchEvent 扩展点。

在代码编辑器中，打开快速入门项目。
打开位于项目根目录处的 manifest.xml 文件。
选择整个 <VersionOverrides> 节点 (包括打开和关闭标记) ，并将其替换为以下 XML，然后保存所做的更改。

<VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides" xsi:type="VersionOverridesV1_0">
  <VersionOverrides xmlns="http://schemas.microsoft.com/office/mailappversionoverrides/1.1" xsi:type="VersionOverridesV1_1">
    <Requirements>
      <bt:Sets DefaultMinVersion="1.10">
        <bt:Set Name="Mailbox" />
      </bt:Sets>
    </Requirements>
    <Hosts>
      <Host xsi:type="MailHost">
        <!-- Event-based activation happens in a lightweight runtime.-->
        <Runtimes>
          <!-- HTML file including reference to or inline JavaScript event handlers.
               This is used by Outlook on the web and Outlook on the new Mac UI. -->
          <Runtime resid="WebViewRuntime.Url">
            <!-- JavaScript file containing event handlers. This is used by Outlook on Windows. -->
            <Override type="javascript" resid="JSRuntime.Url"/>
          </Runtime>
        </Runtimes>
        <DesktopFormFactor>
          <FunctionFile resid="Commands.Url" />
          <ExtensionPoint xsi:type="MessageReadCommandSurface">
            <OfficeTab id="TabDefault">
              <Group id="msgReadGroup">
                <Label resid="GroupLabel" />
                <Control xsi:type="Button" id="msgReadOpenPaneButton">
                  <Label resid="TaskpaneButton.Label" />
                  <Supertip>
                    <Title resid="TaskpaneButton.Label" />
                    <Description resid="TaskpaneButton.Tooltip" />
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16" />
                    <bt:Image size="32" resid="Icon.32x32" />
                    <bt:Image size="80" resid="Icon.80x80" />
                  </Icon>
                  <Action xsi:type="ShowTaskpane">
                    <SourceLocation resid="Taskpane.Url" />
                  </Action>
                </Control>
                <Control xsi:type="Button" id="ActionButton">
                  <Label resid="ActionButton.Label"/>
                  <Supertip>
                    <Title resid="ActionButton.Label"/>
                    <Description resid="ActionButton.Tooltip"/>
                  </Supertip>
                  <Icon>
                    <bt:Image size="16" resid="Icon.16x16"/>
                    <bt:Image size="32" resid="Icon.32x32"/>
                    <bt:Image size="80" resid="Icon.80x80"/>
                  </Icon>
                  <Action xsi:type="ExecuteFunction">
                    <FunctionName>action</FunctionName>
                  </Action>
                </Control>
              </Group>
            </OfficeTab>
          </ExtensionPoint>

          <!-- Can configure other command surface extension points for add-in command support. -->

          <!-- Enable launching the add-in on the included events. -->
          <ExtensionPoint xsi:type="LaunchEvent">
            <LaunchEvents>
              <LaunchEvent Type="OnNewMessageCompose" FunctionName="onNewMessageComposeHandler"/>
              <LaunchEvent Type="OnNewAppointmentOrganizer" FunctionName="onNewAppointmentComposeHandler"/>
              
              <!-- Other available events -->
              <!--
              <LaunchEvent Type="OnMessageAttachmentsChanged" FunctionName="onMessageAttachmentsChangedHandler" />
              <LaunchEvent Type="OnAppointmentAttachmentsChanged" FunctionName="onAppointmentAttachmentsChangedHandler" />
              <LaunchEvent Type="OnMessageRecipientsChanged" FunctionName="onMessageRecipientsChangedHandler" />
              <LaunchEvent Type="OnAppointmentAttendeesChanged" FunctionName="onAppointmentAttendeesChangedHandler" />
              <LaunchEvent Type="OnAppointmentTimeChanged" FunctionName="onAppointmentTimeChangedHandler" />
              <LaunchEvent Type="OnAppointmentRecurrenceChanged" FunctionName="onAppointmentRecurrenceChangedHandler" />
              <LaunchEvent Type="OnInfoBarDismissClicked" FunctionName="onInfobarDismissClickedHandler" />
              <LaunchEvent Type="OnMessageSend" FunctionName="onMessageSendHandler" SendMode="PromptUser" />
              <LaunchEvent Type="OnAppointmentSend" FunctionName="onAppointmentSendHandler" SendMode="PromptUser" />
              <LaunchEvent Type="OnMessageCompose" FunctionName="onMessageComposeHandler" />
              <LaunchEvent Type="OnAppointmentOrganizer" FunctionName="onAppointmentOrganizerHandler" />
              -->
            </LaunchEvents>
            <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
            <SourceLocation resid="WebViewRuntime.Url"/>
          </ExtensionPoint>
        </DesktopFormFactor>
      </Host>
    </Hosts>
    <Resources>
      <bt:Images>
        <bt:Image id="Icon.16x16" DefaultValue="https://localhost:3000/assets/icon-16.png"/>
        <bt:Image id="Icon.32x32" DefaultValue="https://localhost:3000/assets/icon-32.png"/>
        <bt:Image id="Icon.80x80" DefaultValue="https://localhost:3000/assets/icon-80.png"/>
      </bt:Images>
      <bt:Urls>
        <bt:Url id="Commands.Url" DefaultValue="https://localhost:3000/commands.html" />
        <bt:Url id="Taskpane.Url" DefaultValue="https://localhost:3000/taskpane.html" />
        <bt:Url id="WebViewRuntime.Url" DefaultValue="https://localhost:3000/commands.html" />
        <!-- Entry needed for Outlook on Windows. -->
        <bt:Url id="JSRuntime.Url" DefaultValue="https://localhost:3000/launchevent.js" />
      </bt:Urls>
      <bt:ShortStrings>
        <bt:String id="GroupLabel" DefaultValue="Contoso Add-in"/>
        <bt:String id="TaskpaneButton.Label" DefaultValue="Show Taskpane"/>
        <bt:String id="ActionButton.Label" DefaultValue="Perform an action"/>
      </bt:ShortStrings>
      <bt:LongStrings>
        <bt:String id="TaskpaneButton.Tooltip" DefaultValue="Opens a pane displaying all available properties."/>
        <bt:String id="ActionButton.Tooltip" DefaultValue="Perform an action when clicked."/>
      </bt:LongStrings>
    </Resources>
  </VersionOverrides>
</VersionOverrides>

Windows 上的 Outlook 使用 JavaScript 文件，而 Outlook 网页版和新的 Mac UI 上使用可以引用相同 JavaScript 文件的 HTML 文件。您必须在清单的 Resources 节点中提供对这两个文件的引用，因为 Outlook 平台最终会根据 Outlook 客户端确定是使用 HTML 还是 JavaScript。因此，若要配置事件处理，请在 Runtime> 元素中<提供 HTML 的位置，然后在其Override子元素中提供 HTML 内联或引用的 JavaScript 文件的位置。

打开 manifest.json 文件。
将以下对象添加到“extensions.runtimes”数组。关于此标记，请注意以下几点：
- 邮箱要求集的“minVersion”设置为“1.10”，因为本文前面的表指定这是支持 OnNewMessageCompose 和 OnNewAppointmentCompose 事件的要求集的最低版本。
- 运行时的“id”设置为描述性名称“autorun_runtime”。
- “code”属性具有设置为 HTML 文件的子“page”属性，以及设置为 JavaScript 文件的子“script”属性。稍后的步骤将创建或编辑这些文件。 Office 根据平台使用这些值之一。
  - Windows 上的 Office 在仅限 JavaScript 的运行时中执行事件处理程序，该运行时直接加载 JavaScript 文件。
  - Office on Mac 和 Web 在浏览器运行时中执行处理程序，这将加载 HTML 文件。该文件又包含一个 <script> 用于加载 JavaScript 文件的标记。有关详细信息，请参阅 Office 外接程序中的运行时。
- “lifetime”属性设置为“short”，这意味着运行时在触发其中一个事件时启动，并在处理程序完成时关闭。 (在某些情况下，运行时在处理程序完成之前关闭。请参阅 Office Add-ins.) 中的运行时
- 有两种类型的“操作”可以在运行时中运行。在后面的步骤中，你将创建与这些操作对应的函数。
```
 {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.10"
            }
        ]
    },
    "id": "autorun_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/launchevent.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onNewMessageComposeHandler",
            "type": "executeFunction",
            "displayName": "onNewMessageComposeHandler"
        },
        {
            "id": "onNewAppointmentComposeHandler",
            "type": "executeFunction",
            "displayName": "onNewAppointmentComposeHandler"
        }
    ]
}
```
将以下“autoRunEvents”数组添加为“extensions”数组中的对象的属性。
```
"autoRunEvents": [

]
```

将以下对象添加到“autoRunEvents”数组。 “events”属性将处理程序映射到事件，如本文前面的表中所述。处理程序名称必须与前面步骤中“actions”数组中对象的“id”属性中使用的名称匹配。

  {
      "requirements": {
          "capabilities": [
              {
                  "name": "Mailbox",
                  "minVersion": "1.10"
              }
          ],
          "scopes": [
              "mail"
          ]
      },
      "events": [
          {
              "type": "newMessageComposeCreated",
              "actionId": "onNewMessageComposeHandler"
          },
          {
              "type": "newAppointmentOrganizerCreated",
              "actionId": "onNewAppointmentComposeHandler"
          }
      ]
  }

提示

若要了解外接程序中的运行时，请参阅 Office 外接程序中的运行时。
若要详细了解 Outlook 外接程序清单，请参阅 Office 外接程序清单。

实现事件处理

必须对所选事件实现处理。

在此方案中，你将添加用于撰写新项的处理。

在同一个快速入门项目中，在 ./src 目录下创建名为 startvent 的新文件夹。
在 ./src/startvent 文件夹中，创建一个名为 launchevent.js的新文件。

在代码编辑器中打开文件 ./src/startvent/launchevent.js 并添加以下 JavaScript 代码。

/*
* Copyright (c) Microsoft Corporation. All rights reserved. Licensed under the MIT license.
* See LICENSE in the project root for license information.
*/

function onNewMessageComposeHandler(event) {
  setSubject(event);
}
function onNewAppointmentComposeHandler(event) {
  setSubject(event);
}
function setSubject(event) {
  Office.context.mailbox.item.subject.setAsync(
    "Set by an event-based add-in!",
    {
      "asyncContext": event
    },
    function (asyncResult) {
      // Handle success or error.
      if (asyncResult.status !== Office.AsyncResultStatus.Succeeded) {
        console.error("Failed to set subject: " + JSON.stringify(asyncResult.error));
      }

      // Call event.completed() to signal to the Outlook client that the add-in has completed processing the event.
      asyncResult.asyncContext.completed();
    });
}

// IMPORTANT: To ensure your add-in is supported in the Outlook client on Windows, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
  Office.actions.associate("onNewAppointmentComposeHandler", onNewAppointmentComposeHandler);
}

保存所做的更改。

注意

在为 Windows 上的 Outlook 开发基于事件的外接程序时，必须注意一些限制。若要了解详细信息，请参阅基于事件的激活行为和限制。

更新命令 HTML 文件

在 ./src/commands 文件夹中，打开 commands.html。
紧接在结束头标记 (</head>) 之前，添加一个脚本条目以包含事件处理 JavaScript 代码。
```
<script type="text/javascript" src="../launchevent/launchevent.js"></script>
```
保存所做的更改。

更新 webpack 配置设置

打开在项目的根目录中找到的 webpack.config.js 文件，然后完成以下步骤。

plugins在对象中找到数组，config并在数组的开头添加此新对象。

new CopyWebpackPlugin({
  patterns: [
    {
      from: "./src/launchevent/launchevent.js",
      to: "launchevent.js",
    },
  ],
}),

保存所做的更改。

试用

在项目的根目录中运行以下命令。运行 npm start时，如果本地 Web 服务器尚未运行) 并且加载项将被旁加载，则本地 Web 服务器将启动 (。
```
npm run build
```
```
npm start
```
注意

如果加载项未自动旁加载，请按照旁加载 Outlook 加载项中的说明进行测试，在 Outlook 中手动旁加载加载项。
在 Outlook 网页版中，创建新邮件。
在新 Mac UI 上的 Outlook 中，创建新邮件。
在 Outlook on Windows 中，创建新邮件。

故障排除指南

开发基于事件的外接程序时，可能需要排查加载项未加载或未发生事件等问题。如果遇到开发问题，请参阅接下来的四个部分以获取故障排除指南。

查看基于事件的激活先决条件

验证加载项是否已安装在受支持的 Outlook 客户端上。某些 Outlook 客户端仅支持某些事件。例如，Android 版 Outlook 仅支持事件 OnNewMessageCompose 。有关详细信息，请参阅支持的事件。
验证 Outlook 客户端是否支持处理事件所需的最低要求集。基于事件的激活在要求集 1.10 中引入，后续要求集中现在支持其他事件。有关详细信息，请参阅 Exchange 服务器和 Outlook 客户端支持的事件和要求集。如果要开发使用智能警报功能的外接程序，请参阅支持的客户端和平台部分。
查看基于事件的激活和智能警报功能的预期行为和限制。

检查清单和 JavaScript 要求

确保在加载项清单中满足以下条件。
- 验证加载项的源文件位置 URL 是否公开可用且防火墙未阻止。此 URL 在清单的 SourceLocation 元素中指定。
- <验证 Runtimes> 元素 (XML 清单) 或“code”对象 (统一清单 (预览) ) 是否正确引用了包含事件处理程序的 HTML 或 JavaScript 文件。 Windows 上的 Outlook 在运行时使用 JavaScript 文件，而 Outlook 网页版和新 Mac UI 上使用 HTML 文件。有关如何在清单中配置的示例，请参阅配置清单。
  
  对于 Windows 版 Outlook，必须将所有事件处理 JavaScript 代码捆绑到清单中引用的此 JavaScript 文件中。请注意，大型 JavaScript 捆绑包可能会导致加载项性能出现问题。建议预处理大量操作，以便这些操作不包含在事件处理代码中。
验证 Windows 上的 Outlook 客户端引用的事件处理 JavaScript 文件是否调用 Office.actions.associate。这可确保清单中指定的事件处理程序名称映射到其 JavaScript 对应名称。
提示

如果基于事件的外接程序只有一个由 Outlook 网页版、Windows 和 Mac 引用的 JavaScript 文件，建议检查运行加载项的平台，以确定何时调用 Office.actions.associate，如以下代码所示。
```
if (Office.context.platform === Office.PlatformType.PC || Office.context.platform == null) {
  Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
  Office.actions.associate("onNewAppointmentComposeHandler", onNewAppointmentComposeHandler);
}
```
在 Outlook on Windows 中运行的基于事件的加载项的 JavaScript 代码仅支持 ECMAScript 2016 和更早的规范。要避免的编程语法的一些示例如下所示。
- 避免在代码中使用 async 和 await 语句。在 JavaScript 代码中包含这些内容将导致加载项超时。
- 避免使用条件 (三元) 运算符，因为这会阻止加载项加载。
如果外接程序只有一个由 Outlook 网页版、Windows 和 Mac 引用的 JavaScript 文件，则必须将代码限制为 ECMAScript 2016，以确保外接程序在 Outlook on Windows 中运行。但是，如果有由 Outlook 网页版和 Mac 引用的单独 JavaScript 文件，则可以在该文件中实现稍后的 ECMAScript 规范。

调试加载项

对加载项进行更改时，请注意：
- 如果更新清单，请删除加载项，然后再次旁加载它。如果使用的是 Outlook on Windows，则还必须关闭并重新打开 Outlook。
- 如果对清单以外的文件进行更改，请在 Windows 或 Mac 上关闭并重新打开 Outlook 客户端，或刷新运行Outlook 网页版的浏览器选项卡。
- 如果在执行这些步骤后仍无法看到更改，请清除 Office 缓存。
在 Windows 版 Outlook 中测试加载项时：
- 检查事件查看器是否有任何报告的加载项错误。
  1. 在“事件查看器”中，选择“Windows 日志>应用程序”。
  2. 在 “操作” 面板中，选择“ 筛选当前日志”。
  3. 从“ 记录” 下拉列表中，选择首选的日志时间范围。
  4. 选中 “错误 ”复选框。
  5. 在 “事件 ID” 字段中，输入 63。
  6. 选择 “确定” 以应用筛选器。
- 验证 bundle.js 文件是否已下载到文件资源管理器中的以下文件夹。将括在中的 [] 文本替换为适用的信息。
```
%LOCALAPPDATA%\Microsoft\Office\16.0\Wef\{[Outlook profile GUID]}\[Outlook mail account encoding]\Javascript\[Add-in ID]_[Add-in Version]_[locale]
```
  提示
  
  如果 bundle.js 文件未显示在 Wef 文件夹中，请尝试以下操作：
  - 如果加载项已安装或旁加载，请重启 Outlook。
  - 从 Outlook 中删除加载项，然后再次旁加载它。
在 Windows 或 Mac 版 Outlook 中测试加载项时，请启用运行时日志记录以识别可能的清单和加载项安装问题。有关如何使用运行时日志记录的指南，请参阅使用运行时日志记录调试加载项。
在代码中设置断点以调试加载项。有关特定于平台的说明，请参阅调试基于事件的 Outlook 外接程序。

寻求其他帮助

如果在执行建议的故障排除步骤后仍需要帮助，请打开 GitHub 问题。包括屏幕截图、视频录制或运行时日志，以补充报表。

部署到用户

基于事件的外接程序仅限于管理员管理的部署，即使它们是从 AppSource 获取的。如果用户从 AppSource 或应用内 Office 应用商店获取加载项，他们将无法激活外接程序的基于事件的函数。若要详细了解如何在 AppSource 中列出基于事件的外接程序，请参阅基于事件的 Outlook 加载项的 AppSource 列表选项。

管理员部署是通过将清单上传到Microsoft 365 管理中心来完成的。在管理门户中，展开导航窗格中的 “设置” 部分，然后选择“ 集成应用”。在 “集成应用 ”页上，选择“ 上传自定义应用” 操作。

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

重要

如果清单的发送模式属性设置为提示用户或软阻止选项，则使用智能警报功能的加载项只能发布到 AppSource。如果加载项的发送模式属性设置为阻止，则只能由组织的管理员部署，因为它将失败 AppSource 验证。

部署清单更新

由于基于事件的加载项由管理员部署，因此对清单所做的任何更改都需要通过Microsoft 365 管理中心获得管理员同意。在管理员接受更改之前，将阻止其组织中的用户使用加载项。若要详细了解管理员同意过程，请参阅管理员同意安装基于事件的加载项。

基于事件的激活行为和限制

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

如果用户有多个订阅同一事件的加载项，Outlook 平台将不按特定顺序启动加载项。目前，只有五个基于事件的加载项可以主动运行。

在所有受支持的 Outlook 客户端中，用户必须保留在激活加载项的当前邮件项目上，才能完成运行。例如，从当前项 (导航，切换到另一个撰写窗口或选项卡) 将终止加载项操作。当用户发送他们正在撰写的邮件或约会时，加载项也会停止操作。

开发在 Outlook on Windows 客户端中运行的基于事件的外接程序时，请注意以下事项：

在 JavaScript 文件中，你实现基于事件的激活处理的 JavaScript 文件中不支持导入。
加载项不运行和 Office.initialize中包含的Office.onReady()代码。建议改为将任何启动逻辑（例如检查用户的 Outlook 版本）添加到事件处理程序。
基于事件的激活仅支持清单中引用的 JavaScript 文件。必须将事件处理 JavaScript 代码捆绑到此单个文件中。在清单中引用的 JavaScript 文件的位置因外接程序使用的清单类型而异。
- XML 清单：<重写>运行时>节点的<子元素
- Microsoft 365 (预览版的统一清单) ：“code”对象的“script”属性
请注意，大型 JavaScript 捆绑包可能会导致加载项性能出现问题。建议预处理大量操作，以便这些操作不包含在事件处理代码中。

某些 Office.js API 不允许从基于事件的外接程序更改或更改 UI。以下是阻止的 API。

在下 Office.context.auth：
- getAccessToken
- getAccessTokenAsync
  
  注意
  
  支持基于事件的激活和单一登录 (SSO) 的所有 Outlook 版本都支持 OfficeRuntime.auth，而 Office.auth 仅在某些 Outlook 版本中受支持。有关详细信息，请参阅在基于事件的 Outlook 外接程序中启用单一登录 (SSO) 或跨源资源共享 (CORS) 。
在下 Office.context.mailbox：
- displayAppointmentForm
- displayMessageForm
- displayNewAppointmentForm
- displayNewMessageForm
在下 Office.context.mailbox.item：
- close
在下 Office.context.ui：
- displayDialogAsync
- messageParent

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

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

在注册表中，导航到 HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer。如果该键不存在，请创建它。
创建名为的 EnableBetaAPIsInJavaScript 条目，并将其值设置为 1。

启用单一登录 (SSO)

若要在基于事件的外接程序中启用 SSO，必须将其 JavaScript 文件添加到已知 URI。有关如何配置此资源的指南，请参阅在基于事件的 Outlook 外接程序中启用单一登录 (SSO) 或跨源资源共享 (CORS) 。

请求外部数据

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

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

简单的 CORS 实现：

无法使用 Cookie。
仅支持简单方法，例如 GET、 HEAD和 POST。
接受具有字段名称 Accept、 Accept-Language或 Content-Language的简单标头。
可以使用， Content-Type前提是内容类型为 application/x-www-form-urlencoded、 text/plain或 multipart/form-data。
不能在返回 XMLHttpRequest.upload的对象上注册事件侦听器。
不能在请求中使用 ReadableStream 对象。

若要使基于事件的外接程序能够发出 CORS 请求，必须将外接程序及其 JavaScript 文件添加到已知 URI。有关如何配置此资源的指南，请参阅在基于事件的 Outlook 外接程序中启用单一登录 (SSO) 或跨源资源共享 (CORS) 。

注意

从版本 2201、内部版本 16.0.14813.10000) 开始，Outlook 网页版、Mac 和 Windows (提供完整的 CORS 支持。