通过

自动设置新邮件或约会的主题

需要向所有邮件添加所需的免责声明？ 使用基于事件的外接程序，内容会自动添加到新邮件或约会中。 用户可以专注于写作，而不是合规性。

以下部分介绍如何开发处理 OnNewMessageCompose 和 OnNewAppointmentOrganizer 事件的加载项。 在本演练结束时，你将拥有一个加载项，该加载项会自动设置正在创建新邮件和约会的主题。

注意

设置环境

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

配置清单

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

注意

使用 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.10" ，因为这是支持 OnNewMessageCompose 和 OnNewAppointmentOrganizer 事件的要求集的最低版本。

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

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

      • Windows 上的 Office 在仅限 JavaScript 的运行时中执行事件处理程序，该运行时直接加载 JavaScript 文件。
      • Office on Mac 和 Web 版， 以及新的 Outlook on Windows 在浏览器运行时中执行处理程序，这将加载 HTML 文件。 该文件又包含一个 <script> 用于加载 JavaScript 文件的标记。

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

    • 属性 "lifetime" 设置为 "short"，这意味着运行时在触发其中一个事件时启动，并在处理程序完成时关闭。 (在某些情况下，运行时在处理程序完成之前关闭。请参阅 Office Add-ins.) 中的运行时

    • 有两种类型的 "actions" 可以在运行时中运行。 在后面的步骤中，你将创建与这些作对应的函数。

     {
    "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"
        }
    ]
}

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

    "autoRunEvents": [

]

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

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

提示

实现事件处理

  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.
*/

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 Outlook, remember to map the event handler name specified in the manifest to its JavaScript counterpart.
Office.actions.associate("onNewMessageComposeHandler", onNewMessageComposeHandler);
Office.actions.associate("onNewAppointmentComposeHandler", onNewAppointmentComposeHandler);

  4. 保存所做的更改。

注意

  • 在为 Windows 上的经典 Outlook 开发基于事件的外接程序时，必须注意一些限制。 若要了解详细信息，请参阅 基于事件的激活行为和限制。
  • 为确保加载项在事件发生时按预期运行，请在实现处理程序的 JavaScript 文件中调用 Office.actions.associate 。 这会将清单中指定的事件处理程序名称映射到其 JavaScript 对应名称。 清单中处理程序名称的位置因外接程序使用的清单类型而异。

更新命令 HTML 文件

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

  2. 紧接在结束 头 标记 (</head>) 之前，添加一个脚本条目以包含事件处理 JavaScript 代码。

    <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 on Windows 中，创建新邮件。

    Outlook 网页版中的邮件窗口，主题在撰写时设置。

  3. 在新 Mac UI 上的 Outlook 中，创建新邮件。

    Outlook 中新 Mac UI 上的邮件窗口，主题设置为撰写。

  4. 在经典 Outlook on Windows 中，创建新邮件。

    经典 Outlook on Windows 中的邮件窗口，主题设置为撰写。

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

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

      npm stop

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

后续步骤

若要详细了解基于事件的激活以及可在外接程序中实现的其他事件，请参阅 使用事件激活加载项

另请参阅