通过

在 Exchange 帐户之间切换时自动更新签名

现在，通过将 和 OnAppointmentFromChanged 事件添加到OnMessageFromChanged基于事件的激活功能，在使用多个 Exchange 帐户时将正确的签名应用于邮件变得更加容易。 当 OnMessageFromChanged 正在撰写的邮件的“ 发件人 ”字段中的帐户发生更改时，将发生该事件，而 OnAppointmentFromChanged 当正在撰写的会议的组织者发生更改时，将发生该事件。 这些事件进一步扩展了签名加载项的功能，并允许它们：

  • 为用户提供为其每个帐户应用自定义签名的便利。
  • 使邮箱代理能够更准确、更高效地管理来自多个邮箱的传出邮件和会议请求。
  • 确保用户的消息和约会符合其组织的通信和营销策略。

以下部分将指导你如何开发基于事件的外接程序，该外接程序处理 OnMessageFromChanged 事件，以在更改“ 发件人 ”字段中的邮件帐户时自动更新邮件的签名。

注意

OnMessageFromChanged和 OnAppointmentFromChanged 事件在要求集 1.13 中引入。 有关这些事件的客户端支持的信息，请参阅 支持的客户端和平台。

支持的客户端和平台

下表列出了支持 OnMessageFromChanged 和 OnAppointmentFromChanged 事件的客户端-服务器组合。 选择适用事件的选项卡。

客户端 Exchange Online Exchange Server订阅版 (SE) Exchange 2019 本地 (累积更新 12 或更高版本) Exchange 2016 本地 (累积更新 22 或更高版本)
Web 浏览器 (新式 UI)

新的 Outlook on Windows		 支持 不适用 不适用 不适用
Windows (经典)
版本 2304 (内部版本 16327.20248) 或更高版本		 支持 支持 支持 支持
Mac
版本 16.77 (23081600) 或更高版本		 支持 不适用 不适用 不适用
iOS
版本 4.2502.0		 支持 不适用 不适用 不适用
Android
版本 4.2502.0		 支持 不适用 不适用 不适用

先决条件

若要测试演练，必须至少有两个 Exchange 帐户。

设置环境

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

配置清单

注意

Outlook 网页版 OnMessageFromChanged 中的 Microsoft 365 的统一清单和新的 Windows 版 Outlook 目前不提供该事件。 若要处理这些事件，请改为实现仅外接程序清单。 有关清单类型的信息，请参阅 Office 外接程序清单。

注意

使用 Microsoft 365 统一清单的加载项在 Outlook on Mac 和移动设备上不受直接支持。 若要在 Mac 和移动平台上运行这种类型的外接程序，必须先将外接程序发布到Microsoft市场，然后部署在 Microsoft 365 管理 中心。 有关详细信息，请参阅 Office 加载项的“客户端和平台支持”部分 ，其中包含 Microsoft 365 的统一应用清单。

  1. 打开 manifest.json 文件。

  2. 导航到 "authorization.permissions.resourceSpecific" 数组。 在数组对象中，将 属性"MailboxItem.ReadWrite.User"的值"name"替换为 。 加载项需要此项才能更新消息的签名。

    ...
"authorization": {
    "permissions": {
        "resourceSpecific": [
            {
                "name": "MailboxItem.ReadWrite.User",
                "type": "Delegated"
            }
        ]
    }
},
...

  3. 将以下对象添加到 "extensions.runtimes" 数组中。 关于此标记，请注意以下几点。

    • "minVersion"邮箱要求集的 配置为 "1.13" ，因为这是支持OnMessageFromChanged事件的要求集的最低版本。 有关详细信息，请参阅使用事件 激活加载项中的“支持的事件”表。

    • "id"运行时的 设置为描述性名称 "autorun_runtime"。

    • 属性 "code" 的子 "page" 属性设置为 HTML 文件，子 "script" 属性设置为 JavaScript 文件。 稍后的步骤将创建或编辑这些文件。 Office 根据平台使用这些值之一。

      • 经典 Outlook on Windows 在仅限 JavaScript 的运行时中执行事件处理程序，该运行时直接加载 JavaScript 文件。
      • Outlook 网页版 和 Mac 上，新的 Outlook on Windows 在浏览器运行时中执行处理程序，这将加载 HTML 文件。 HTML 文件包含随后 <script> 加载 JavaScript 文件的标记。

      有关详细信息，请参阅 Office 外接程序中的运行时。

    • "lifetime" 属性设置为 "short"。 这意味着运行时在事件发生时启动，并在处理程序完成时关闭。

    • 需要 "actions" 为 OnMessageFromChanged 和 OnNewMessageCompose 事件运行处理程序。 你将在后面的步骤中创建处理程序。

    {
    "requirements": {
        "capabilities": [
            {
                "name": "Mailbox",
                "minVersion": "1.13"
            }
        ]
    },
    "id": "autorun_runtime",
    "type": "general",
    "code": {
        "page": "https://localhost:3000/commands.html",
        "script": "https://localhost:3000/launchevent.js"
    },
    "lifetime": "short",
    "actions": [
        {
            "id": "onMessageFromChangedHandler",
            "type": "executeFunction",
            "displayName": "onMessageFromChangedHandler"
        },
        {
            "id": "onNewMessageComposeHandler",
            "type": "executeFunction",
            "displayName": "onNewMessageComposeHandler"
        }
    ]
}

  4. "autoRunEvents"将数组添加为数组中 "extensions" 对象的属性。 数组 "autoRunEvents" 包含具有以下键属性的对象。

    • 属性 "events" 将处理程序分配给 OnMessageFromChanged 和 OnNewMessageCompose 事件。 有关统一清单中使用的事件名称的信息，请参阅 使用事件激活加载项中的“支持的事件”表。
    • 中"actionId"提供的函数名称必须与前面配置的数组中"actions"其相应对象的 属性匹配"id"。
    "autoRunEvents": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ],
            "scopes": [
                "mail"
            ]
        },
        "events": [
            {
                "type": "messageFromChanged",
                "actionId": "onMessageFromChangedHandler"
            },
            {
                "type": "newMessageComposeCreated",
                "actionId": "onNewMessageComposeHandler"
            }
        ]
    }
]

提示

实现事件处理程序

必须为 和 OnMessageFromChanged 事件配置OnNewMessageCompose事件处理程序。 如果当前帐户上尚未配置默认签名，则 onNewMessageComposeHandler 函数会将签名添加到新创建的消息。 更改“ 发件人 ”字段中的帐户时， onMessageFromChangedHandler 函数会基于此新选择的帐户更新签名。

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

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

  3. 在代码编辑器中打开文件 ./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.
 */

// The OnNewMessageCompose event handler that adds a signature to a new message.
function onNewMessageComposeHandler(event) {
    const platform = Office.context.platform;
    const signature = "<i>This is a sample signature.</i>";

    // On supported platforms, check if a default Outlook signature is already configured.
    if (platform !== Office.PlatformType.Android && platform !== Office.PlatformType.iOS) {
        Office.context.mailbox.item.isClientSignatureEnabledAsync({ asyncContext: { event: event, signature: signature } }, (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                console.log(result.error.message);
                return;
            }

            // Add a signature if there's no default Outlook signature configured.
            const signatureEnabled = result.value;
            if (signatureEnabled === false) {
                const event = result.asyncContext.event;
                const signature = result.asyncContext.signature;
                setSignature(signature, event);
            }
        });
    } else {
        setSignature(signature, event);
    }
}

// The OnMessageFromChanged event handler that updates the signature when the email address in the From field is changed.
function onMessageFromChangedHandler(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 currently selected From account.
    item.from.getAsync({ asyncContext: event }, (result) => {
        if (result.status === Office.AsyncResultStatus.Failed) {
            console.log(result.error.message);
            return;
        }

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

            // Add the created signature to the mail item.
            const signature = "<img src='cid:signatureIcon.png'>" + result.asyncContext.name;
            const event = result.asyncContext.event;
            setSignature(signature, event);
        });
    });
}

// Sets the custom signature and adds it to the mail item.
function setSignature(signature, event) {
    Office.context.mailbox.item.body.setSignatureAsync(
        signature,
        { asyncContext: event, coercionType: Office.CoercionType.Html },
        (result) => {
            if (result.status === Office.AsyncResultStatus.Failed) {
                console.log(result.error.message);
                return;
            }

            console.log("Successfully added signature.");
            const event = result.asyncContext;
            event.completed();
        }
    );
}

// IMPORTANT: To ensure your add-in is supported in Outlook, remember to
// map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
Office.actions.associate("onMessageFromChangedHandler", onMessageFromChangedHandler);

重要

  • 在经典 Outlook on Windows 中，导入在 JavaScript 文件中不受支持，可在其中实现基于事件的激活的处理。
  • 在经典 Outlook on Windows 中，当清单中指定的用于处理事件的 JavaScript 函数运行时，代码不会Office.onReady()Office.initialize运行。 建议改为将事件处理程序所需的任何启动逻辑（例如检查用户的 Outlook 版本）添加到事件处理程序。
  • 为确保加载项在事件发生时按预期运行，请在实现处理程序的 JavaScript 文件中调用 Office.actions.associate 。 这会将清单中指定的事件处理程序名称映射到其 JavaScript 对应名称。 清单中处理程序名称的位置因外接程序使用的清单类型而异。

更新命令 HTML 文件

  1. 在 ./src/commands 文件夹中，打开 commands.html。

  2. 在现有 脚本 标记下面添加以下代码。

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

  3. 保存所做的更改。

更新 webpack 配置设置

  1. 从项目的根目录中，打开 webpack.config.js 文件。

  2. plugins在 对象中找到数组，config并将以下新对象添加到数组的开头。

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

  3. 保存所做的更改。

试用

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

    npm run build

    npm start

    注意

    • 首次使用 Yeoman 生成器开发 Office 加载项时，默认浏览器会打开一个窗口，提示你登录到 Microsoft 365 帐户。 如果未显示登录窗口，并且遇到旁加载或登录超时错误，请在再次运行npm start之前运行atk auth login m365。

    如果加载项未自动旁加载，请按照 旁加载 Outlook 外接程序 中的说明进行测试，在 Outlook 中手动旁加载加载项。

  2. 在首选 Outlook 客户端中，创建新邮件。 如果未配置默认 Outlook 签名，外接程序会将一个添加到新创建的邮件。 在移动设备上的 Outlook 中，即使配置了默认签名，加载项也会添加示例签名。

    未在帐户上配置默认 Outlook 签名时，添加到新撰写的邮件的示例签名。

  3. 启用“ 发件人 ”字段（如果适用）。 有关如何启用它的指南，请参阅 更改用于发送电子邮件的帐户的“为什么缺少发件人按钮？”部分。

  4. 选择“ 发件人”，然后选择其他 Exchange 帐户。 或者，通过选择“从>其他Email地址”手动输入 Exchange 电子邮件地址。 已更新的签名将添加到消息中，替换上一个签名。

    更改“发件人”字段中的帐户时，包含徽标的已更新签名示例。

  5. 如果要停止本地 Web 服务器并卸载加载项，请按照适用的说明作：

    • 若要停止服务器，请运行以下命令。 如果使用 npm start了 ，则以下命令还应卸载加载项。

      npm stop

    • 如果手动旁加载加载项，请参阅 删除旁加载加载项。

排查加载项问题

有关如何排查基于事件的激活加载项的指南，请参阅 基于事件的加载项和垃圾邮件报告加载项疑难解答。

部署到用户

与其他基于事件的外接程序类似，使用 OnMessageFromChanged 和 OnAppointmentFromChanged 事件的加载项必须由组织的管理员部署。 有关如何通过Microsoft 365 管理中心部署加载项的指南，请参阅使用事件激活加载项的“部署外接程序”部分。

事件行为和限制

OnMessageFromChanged由于 和 OnAppointmentFromChanged 事件通过基于事件的激活功能受支持，因此相同的行为和限制适用于因此事件而激活的加载项。 有关详细说明，请参阅 基于事件的激活行为和限制。

除了这些特征之外，当加载项在这些事件上激活时，以下方面也适用。

  • 事件 OnMessageFromChanged 仅在邮件撰写模式下受支持，而 OnAppointmentFromChanged 事件仅在约会撰写模式下受支持。
  • 在 Outlook 网页版 中，在 Windows (新) 和经典) ，在移动设备上，仅OnMessageFromChanged支持事件。
  • OnMessageFromChanged和 OnAppointmentFromChanged 事件仅支持 Exchange 帐户。 如果用户切换到“ 发件人 ”或“组织者”字段中的非 Exchange 帐户，Outlook 客户端会自动清除以前所选帐户设置的签名。
  • 根据 Outlook 客户端，在撰写的邮件中，从“ 发件人 ”字段下拉列表中选择 Exchange 帐户或在字段中手动输入。 移动设备上的 Outlook 仅支持从“ 发件人 ”字段下拉列表中选择帐户。 在撰写的约会中，从组织者字段下拉列表中选择 Exchange 帐户。
  • 在 Outlook 网页版 中，在 Windows (新) 和经典) ，在 Mac 上， OnMessageFromChanged 和 OnAppointmentFromChanged 事件支持委托和共享邮箱方案。 移动设备上的 Outlook 不支持这些方案。
  • OnAppointmentFromChanged Microsoft 365 组日历不支持该事件。 如果用户从其 Exchange 帐户切换到组织者字段中的 Microsoft 365 组日历帐户，Outlook 客户端会自动清除 Exchange 帐户设置的签名。
  • 在“发件人”或“组织者”字段中切换到另一个 Exchange 帐户时，将终止以前所选帐户的加载项（如果有），并与新选择的帐户关联的外接程序在启动 或 OnAppointmentFromChanged 事件之前OnMessageFromChanged加载。
  • 在 Outlook 网页版 中，在 Windows (新的和经典) ，在 Mac 上，支持电子邮件帐户别名。 在“发件人”或“组织者”字段中选择当前帐户的别名时，OnMessageFromChanged将发生 或 OnAppointmentFromChanged 事件，而无需重新加载帐户的加载项。Email移动设备上的 Outlook 不支持帐户别名。
  • 当错误打开“ 发件人 或组织者”字段下拉列表或重新选择“ 发件人 或组织者”字段中显示的同一帐户时， OnMessageFromChanged 将发生 或 OnAppointmentFromChanged 事件，但不会终止或重新加载帐户的加载项。

另请参阅