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

项目
02/29/2024

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

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

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

注意

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

支持的客户端

从版本 4.2352.0 开始，本演练中开发的加载项在 Android 版 Outlook 和 iOS 上受支持。必须拥有 Microsoft 365 订阅才能运行该功能。

设置环境

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

配置清单

注意

移动设备目前不支持统一 Microsoft 365 清单 (预览版) 。

若要在 Outlook 移动版上启用基于事件的外接程序，必须在清单的节点中 VersionOverridesV1_1 配置以下元素。

在 Runtimes 元素中，指定引用事件处理 JavaScript 文件的 HTML 文件。
添加 MobileFormFactor 元素，使外接程序在 Outlook mobile 中可用。
xsi:type将 ExtensionPoint 元素的设置为 LaunchEvent。这将在 Outlook 移动加载项中启用基于事件的激活功能。
在 LaunchEvent 元素中，将设置为 TypeOnNewMessageCompose ，并在特性中 FunctionName 指定事件处理程序的 JavaScript 函数名称。

在代码编辑器中，打开创建的快速入门项目。
打开位于项目根目录处的 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.5">
                <bt:Set Name="Mailbox"/>
            </bt:Sets>
        </Requirements>
        <Hosts>
            <Host xsi:type="MailHost">
                <!-- The HTML file that references or contains the JavaScript event handlers.
                    This is used by Outlook on mobile devices. -->
                <Runtimes>
                    <Runtime resid="WebViewRuntime.Url">
                    </Runtime>
                </Runtimes>
                <!-- Defines the add-in for Outlook on Windows (classic and new (preview)), on Mac, and on the web. -->
                <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>
                </DesktopFormFactor>
                <!-- Defines the add-in for Outlook mobile. -->
                <MobileFormFactor>
                    <!-- Configures event-based activation. -->
                    <ExtensionPoint xsi:type="LaunchEvent">
                        <LaunchEvents>
                            <LaunchEvent Type="OnNewMessageCompose" FunctionName="onNewMessageComposeHandler"/>
                        </LaunchEvents>
                        <!-- Identifies the runtime to be used (also referenced by the Runtime element). -->
                        <SourceLocation resid="WebViewRuntime.Url"/>
                    </ExtensionPoint>
                </MobileFormFactor>
            </Host>
        </Hosts>
        <!-- This manifest uses a fictitious web server, contoso.com, to host the add-in's files.
             Replace these instances with the information of the web server that hosts your add-in's files. -->
        <Resources>
            <bt:Images>
                <bt:Image id="Icon.16x16" DefaultValue="https://contoso.com/assets/icon-16.png"/>
                <bt:Image id="Icon.32x32" DefaultValue="https://contoso.com/assets/icon-32.png"/>
                <bt:Image id="Icon.80x80" DefaultValue="https://contoso.com/assets/icon-80.png"/>
            </bt:Images>
            <bt:Urls>
                <bt:Url id="Commands.Url" DefaultValue="https://contoso.com/commands.html"/>
                <bt:Url id="Taskpane.Url" DefaultValue="https://contoso.com/taskpane.html"/>
                <bt:Url id="WebViewRuntime.Url" DefaultValue="https://contoso.com/commands.html"/>
            </bt:Urls>
            <bt:ShortStrings>
                <bt:String id="GroupLabel" DefaultValue="Event-based activation on mobile"/>
                <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>

保存所做的更改。

提示

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

实现事件处理程序

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

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

打开创建的 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();
                });
            });
        });
    });
}

保存所做的更改。

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

确保在清单的 <Runtime> 元素中指定的 HTML 文件具有对包含事件处理程序的 JavaScript 文件的引用。

导航到 ./src/commands 文件夹，然后打开 commands.html。
紧接在结束头标记 (</head>) 之前，为包含事件处理程序的 JavaScript 文件添加脚本条目。
```
<script type="text/javascript" src="../launchevent/launchevent.js"></script>
```
保存所做的更改。

测试和验证加载项

按照指南来测试和验证加载项。
在 Outlook on Windows 中旁加载加载项 (经典版或新的 (预览版) ) 、Mac 版或 Web 版。
在 Android 或 iOS 上打开 Outlook。如果已在设备上打开 Outlook，请重启它。
创建新邮件。基于事件的外接程序向消息添加签名。如果你在移动设备上保存了签名，该签名将短暂显示在你创建的消息中，但将立即替换为加载项添加的签名。

行为和限制

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

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

支持的其他 API

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

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

部署到用户

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