通过

在 Outlook 移动加载项中实现基于事件的激活

  • 项目

使用 基于事件的激活 功能，开发加载项，以在 Android 或 iOS 上的 Outlook 中发生某些事件（例如撰写新邮件）时自动激活和完成操作。

以下部分将引导你完成如何开发 Outlook 移动加载项，该外接程序会自动向撰写的新邮件添加签名。 本文重点介绍了如何在移动加载项中实现基于事件的激活的示例方案。 通过探索加载项中的其他方案和受支持的事件，显著增强移动用户体验。

若要了解如何在 Mac 上和 Web 上实现基于事件的 Outlook (经典和 新的 (预览) ) 的基于事件的外接程序，请参阅 为基于事件的激活配置 Outlook 外接程序。

注意

Android 版和 iOS 版 Outlook 最多支持邮箱要求集 1.5。 但是，为了支持基于事件的激活功能，已在移动客户端上启用了更高要求集中的某些 API。 有关此异常的详细信息，请参阅 其他支持的 API。

支持的事件和客户端

事件规范名称和 XML 清单名称 Microsoft 365 名称的统一应用清单 说明 支持的客户端
OnNewMessageCompose newMessageComposeCreated 在撰写新邮件时发生， (包括答复、全部答复和转发) ，但不在编辑草稿时发生。
  • Android (版本 4.2352.0)
  • iOS (版本 4.2352.0)
OnMessageRecipientsChanged 不可用 在撰写邮件时添加或删除收件人时发生。

特定于事件的数据对象： RecipientsChangedEventArgs
  • Android (版本 4.2425.0)
  • iOS (版本 4.2425.0)

设置环境

若要运行此功能，必须在 Android 或 iOS 上具有受支持的 Outlook 版本， (请参阅 支持的事件和客户端) 和Microsoft 365 订阅。 然后，完成 Outlook 快速入门 ，在其中使用 Office 加载项的 Yeoman 生成器创建外接程序项目。

配置清单

配置清单的步骤取决于在快速入门中选择的清单类型。

注意

开发基于事件的外接程序以在 Android 版 Outlook 和 iOS 上运行时，请注意，仅当加载项处理某些事件时，才能使用 Microsoft 365 的统一应用清单。 若要了解支持哪些事件，请参阅 支持的事件和客户端。

  1. 配置“extensions.runtimes”属性，就像设置函数命令一样。 有关详细信息，请参阅 配置函数命令的运行时。

  2. 在“extensions.ribbons.contexts”数组中，添加 mailRead 为项。 完成后，数组应如下所示。

    "contexts": [
    "mailRead"
],

  3. 在“extensions.ribbons.requirements.formFactors”数组中，添加“mobile”作为项。 完成后，数组应如下所示。

    "formFactors": [
    "mobile",
    <!-- Typically there will be other form factors listed. -->
]

  4. 将以下“autoRunEvents”数组添加为“extensions”数组中的 对象的属性。

    "autoRunEvents": [

]

  5. 将如下所示的对象添加到“autoRunEvents”数组。 关于此代码，请注意以下几点：

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

提示

若要了解有关 Outlook 外接程序清单的详细信息，请参阅 Office 外接程序清单 和在 移动设备上的 Outlook 中添加对外接程序命令的支持。

实现事件处理程序

若要使外接程序能够在事件发生时 OnNewMessageCompose 完成任务，必须实现 JavaScript 事件处理程序。 在本部分中，你将创建 onNewMessageComposeHandler 向撰写的新邮件添加签名的函数，然后显示一条消息以通知签名已添加。

  1. 在同一快速入门项目中，导航到 ./src 目录，然后创建名为 startvent 的新文件夹。

  2. 在 ./src/startvent 文件夹中，创建一个名为 launchevent.js的新文件。

  3. 打开创建的 launchevent.js 文件并添加以下 JavaScript 代码。

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

// Add start-up logic code here, if any.
Office.onReady();

function onNewMessageComposeHandler(event) {
    const item = Office.context.mailbox.item;
    const signatureIcon = "iVBORw0KGgoAAAANSUhEUgAAACcAAAAnCAMAAAC7faEHAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAzUExURQAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAKMFRskAAAAQdFJOUwAQIDBAUGBwgI+fr7/P3+8jGoKKAAAACXBIWXMAAA7DAAAOwwHHb6hkAAABT0lEQVQ4T7XT2ZalIAwF0DAJhMH+/6+tJOQqot6X6joPiouNBo3w9/Hd6+hrYnUt6vhLcjEAJevVW0zJxABSlcunhERpjY+UKoNN5+ZgDGu2onNz0OngjP2FM1VdyBW1LtvGeYrBLs7U5I1PTXZt+zifcS3Icw2GcS3vxRY3Vn/iqx31hUyTnV515kdTfbaNhZLI30AceqDiIo4tyKEmJpKdP5M4um+nUwfDWxAXdzqMNKQ14jLdL5ntXzxcRF440mhS6yu882Kxa30RZcUIjTCJg7lscsR4VsMjfX9Q0Vuv/Wd3YosD1J4LuSRtaL7bzXGN1wx2cytUdncDuhA3fu6HPTiCvpQUIjZ3sCcHVbvLtbNTHlysx2w9/s27m9gEb+7CTri6hR1wcTf2gVf3wBRe3CMbcHYvTODkXhnD0+178K/pZ9+n/C1ru/2HAPwAo7YM1X4+tLMAAAAASUVORK5CYII=";

    // Get the sender's account information.
    item.from.getAsync((result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            event.completed();
            return;
        }

        // Create a signature based on the sender's information.
        const name = result.value.displayName;
        const options = { asyncContext: name, isInline: true };
        item.addFileAttachmentFromBase64Async(signatureIcon, "signatureIcon.png", options, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                console.log(result.error.message);
                event.completed();
                return;
            }

            // Add the created signature to the message.
            const signature = "<img src='cid:signatureIcon.png'>" + result.asyncContext;
            item.body.setSignatureAsync(signature, { coercionType: Office.CoercionType.Html }, (result) => {
                if (result.status === Office.AsyncResultStatus.Failed) {
                    console.log(result.error.message);
                    event.completed();
                    return;
                }

                // Show a notification when the signature is added to the message.
                // Important: Only the InformationalMessage type is supported in Outlook mobile at this time.
                const notification = {
                    type: Office.MailboxEnums.ItemNotificationMessageType.InformationalMessage,
                    message: "Company signature added.",
                    icon: "none",
                    persistent: false                        
                };
                item.notificationMessages.addAsync("signature_notification", notification, (result) => {
                    if (result.status === Office.AsyncResultStatus.Failed) {
                        console.log(result.error.message);
                        event.completed();
                        return;
                    }

                    event.completed();
                });
            });
        });
    });
}

  4. 保存所做的更改。

添加对事件处理 JavaScript 文件的引用

确保 ./src/commands/commands.html 文件引用包含事件处理程序的 JavaScript 文件。

  1. 导航到 ./src/commands 文件夹，然后打开 commands.html。

  2. 紧接在结束 头 标记 (</head>) 之前，为包含事件处理程序的 JavaScript 文件添加脚本条目。

    <script type="text/javascript" src="../launchevent/launchevent.js"></script>

  3. 保存所做的更改。

测试和验证加载项

  1. 按照指南 来测试和验证加载项。

  2. 在 Outlook on Windows 中旁加载加载项 (经典版或新的 (预览版) ) 、Mac 版或 Web 版。

  3. 在 Android 或 iOS 上打开 Outlook。 如果已在设备上打开 Outlook，请重启它。

  4. 创建新邮件。 基于事件的外接程序向消息添加签名。 如果你在移动设备上保存了签名，该签名将短暂显示在你创建的消息中，但将立即替换为加载项添加的签名。

    添加到 Outlook mobile 中撰写的邮件的示例签名。

行为和限制

在为 Outlook 移动版开发基于事件的外接程序时，请注意以下功能行为和限制。

  • 由于基于事件的加载项应是短时间运行且轻型的，因此允许加载项自激活后最多运行 60 秒。 若要指示加载项已完成处理事件，事件处理程序必须调用 event.completed 方法。 当用户关闭撰写窗口或发送消息时，加载项操作也会结束。
  • 一次只能运行一个加载项。 如果在用户的帐户上安装多个基于事件的加载项，它们将按顺序运行。
  • 如果在移动设备上点击并按住 Outlook 图标，然后选择“ 新建邮件 ”以创建新邮件，处理事件的 OnNewMessageCompose 基于事件的外接程序可能需要几秒钟才能初始化并完成事件处理。
  • 使用处理 OnNewMessageCompose 事件的基于事件的外接程序时，如果未对撰写的新邮件进行更改，则不会保存草稿。 即使加载项使用 Office.context.mailbox.item.body.setSignatureAsync 方法添加签名，这一点也适用。
  • 在发生事件时管理签名的基于事件的外接程序中 OnNewMessageCompose ，如果从邮件底部选择“ 答复 ”，外接程序将激活并将签名添加到邮件中。 但是，签名在当前视图中不可见。 若要使用添加的签名查看邮件，请将撰写窗口展开为全屏。
  • 若要增强加载项的功能，可以在撰写模式下使用更高要求集中支持的 API。 有关详细信息，请参阅 其他支持的 API。

支持的其他 API

尽管 Outlook 移动版支持高达 邮箱要求集 1.5 的 API，但为了进一步扩展 Outlook mobile 中基于事件的外接程序的功能，现在在撰写模式下支持来自更高要求集的其他 API。

若要详细了解移动设备上的 Outlook 支持的 API，请参阅移动设备 上的 Outlook 支持的 Outlook JavaScript API。

部署到用户

基于事件的加载项必须由组织的管理员部署。 有关如何通过 Microsoft 365 管理中心部署外接程序的指南，请参阅 配置 Outlook 外接程序进行基于事件的激活的“部署到用户”部分。

另请参阅