通过

在多条消息上激活 Outlook 加载项

  • 项目

借助项多选功能，Outlook 加载项现在可以一次性激活多个所选邮件并对其执行操作。 现在只需单击一下即可轻松完成某些操作，例如将消息上传到客户关系管理 (CRM) 系统或对大量项目进行分类。

以下部分将引导你完成如何配置加载项，以在阅读模式下检索多条消息的主题行。

注意

要求集 1.13 中引入了对项多选功能的支持，后续要求集中现在提供了其他项属性。 请查看支持此要求集的客户端和平台。

设置环境

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

配置清单

  1. 在首选代码编辑器中，打开创建的 Outlook 快速入门项目。

  2. 打开位于项目根目录处的 manifest.json 文件。

  3. 在“authorization.permissions.resourceSpecific”数组中，将“name”属性的值更改为“Mailbox.ReadWrite.User”。 完成后，它应如下所示。

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

  4. 在“extensions.runtimes”数组的第一个对象中，进行以下更改。

    1. 将“requirements.capabilities.minVersion”属性更改为“1.13”。
    2. 在同一“actions”对象中，添加“supportsNoItemContext”属性并将其设置为 true。
    3. 在同一“actions”对象中，添加“multiselect”属性并将其设置为 true。

    更改后，代码应如下所示。

    "runtimes": [
    {
        "requirements": {
            "capabilities": [
                {
                    "name": "Mailbox",
                    "minVersion": "1.13"
                }
            ]
        },
        "id": "TaskPaneRuntime",
        "type": "general",
        "code": {
            "page": "https://localhost:3000/taskpane.html"
        },
        "lifetime": "short",
        "actions": [
            {
                "id": "TaskPaneRuntimeShow",
                "type": "openPage",
                "pinnable": false,
                "view": "dashboard",
                "supportsNoItemContext": true,
                "multiselect": true
            }
        ]
    },
    ...
]

  5. 删除“extensions.runtimes”数组的第二个对象，其“id”为“CommandsRuntime”。

  6. 在“extensions.ribbons.tabs.controls”数组中，删除第二个对象，其“id”为“ActionButton”。

  7. 保存所做的更改。

注意

如果在外接程序中打开项多选功能，外接程序将自动支持 无项上下文 功能，即使未在清单中显式配置此功能也是如此。

配置任务窗格

项多选依赖于 SelectedItemsChanged 事件来确定何时选择或取消选择消息。 此事件需要任务窗格实现。

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

  2. 在 <body> 元素中，将整个 <main> 元素替换为以下标记。

    <main id="app-body" class="ms-welcome__main">
    <h2 class="ms-font-xl">Retrieve the subject line of multiple messages with one click!</h2>
    <ul id="selected-items"></ul>
    <div role="button" id="run" class="ms-welcome__action ms-Button ms-Button--hero ms-font-xl">
        <span class="ms-Button-label">Run</span>
    </div>
</main>

  3. 保存所做的更改。

实现 SelectedItemsChanged 事件的处理程序

若要在事件发生时 SelectedItemsChanged 向外接程序发出警报，必须使用 方法注册事件处理程序 addHandlerAsync 。

  1. 在 ./src/taskpane 文件夹中，打开 taskpane.js。

  2. 在 Office.onReady() 回调函数中，将现有代码替换为以下内容：

    if (info.host === Office.HostType.Outlook) {
    document.getElementById("sideload-msg").style.display = "none";
    document.getElementById("app-body").style.display = "flex";
    document.getElementById("run").onclick = run;

    // Register an event handler to identify when messages are selected.
    Office.context.mailbox.addHandlerAsync(Office.EventType.SelectedItemsChanged, run, asyncResult => {
      if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;
      }

      console.log("Event handler added.");
    });
}

检索所选邮件的主题行

注册事件处理程序后，请调用 getSelectedItemsAsync 方法来检索所选消息的主题行，并将其记录到任务窗格。 方法 getSelectedItemsAsync 还可用于获取其他消息属性，例如项目 ID、项类型 (Message 是目前唯一受支持的类型) ，以及项模式 (Read 或 Compose) 。

  1. 在 taskpane.js中，导航到 run 函数并插入以下代码。

    // Clear list of previously selected messages, if any.
const list = document.getElementById("selected-items");
while (list.firstChild) {
    list.removeChild(list.firstChild);
}

// Retrieve the subject line of the selected messages and log it to a list in the task pane.
Office.context.mailbox.getSelectedItemsAsync(asyncResult => {
    if (asyncResult.status === Office.AsyncResultStatus.Failed) {
        console.log(asyncResult.error.message);
        return;      
    }

    asyncResult.value.forEach(item => {
        const listItem = document.createElement("li");
        listItem.textContent = item.subject;
        list.appendChild(listItem);
    });
});

  2. 保存所做的更改。

试用

  1. 在终端中，在项目的根目录中运行以下代码。 这会启动本地 Web 服务器并旁加载加载项。

    npm start

    提示

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

  2. 在 Outlook 中，确保“阅读窗格”已启用。 若要启用阅读窗格，请参阅 使用和配置阅读窗格以预览消息。

  3. 导航到收件箱，在选择邮件时按住 Ctrl 选择多个邮件。

  4. 从功能区中选择“ 显示任务窗格 ”。

  5. 在任务窗格中，选择“ 运行 ”以查看所选邮件的主题行的列表。

    从多个选定邮件中检索的主题行的示例列表。

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

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

      npm stop

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

项多选行为和限制

项目多选仅支持在阅读和撰写模式下的 Exchange 邮箱内的邮件。 Outlook 加载项仅在满足以下条件时在多条消息上激活。

  • 必须一次从一个 Exchange 邮箱中选择邮件。 不支持非 Exchange 邮箱。
  • 必须一次从一个邮箱文件夹中选择邮件。 如果加载项位于不同的文件夹中，则外接程序不会在多个邮件上激活，除非启用了“对话”视图。 有关详细信息，请参阅 对话中的多选。
  • 加载项必须实现任务窗格才能检测 SelectedItemsChanged 事件。
  • 必须启用 Outlook 中的 阅读窗格 。 这种情况的一个例外是，如果通过清单中的无项上下文功能启用项多选功能。 若要了解详细信息，请参阅 在未启用阅读窗格或未选择邮件的情况下激活 Outlook 加载项。
  • 一次最多可以选择 100 条消息。

注意

会议邀请和响应被视为消息，而不是约会，因此可以包含在所选内容中。

对话中的多选

项目多选支持 对话视图 ，无论是在邮箱还是特定文件夹上启用。 下表描述了展开或折叠对话时的预期行为、选择会话标头以及对话邮件位于当前视图中的文件夹不同的文件夹时的预期行为。

选择 展开的对话视图 折叠对话视图
已选择对话标头 如果对话标头是唯一选定的项目，则支持多选的加载项不会激活。 但是，如果还选择了其他非标头消息，则外接程序将仅在这些邮件头上激活，而不激活所选标头。 行为因 Outlook 客户端而异。

Windows 上的 Outlook (经典) 和 Mac 版：
最新的消息 (，即会话堆栈) 中的第一条消息包含在邮件选择中。

如果对话中的最新邮件位于当前视图中的另一个文件夹中，则位于当前文件夹中的堆栈中的后续邮件将包含在所选内容中。

Outlook 网页版和新的 Windows 版 Outlook：
已选择会话堆栈中的所有消息。 这包括对话中的邮件，这些邮件位于当前视图中的文件夹以外的其他文件夹中。
聊天堆栈中的多个所选邮件与当前视图中的多个邮件位于同一文件夹中 同一对话中的所有所选邮件都包含在所选内容中。 不适用。 必须展开会话堆栈才能从中选择多个消息。
聊天堆栈中的多个所选邮件位于当前视图中的文件夹中的不同文件夹中 同一对话中的所有所选邮件都包含在所选内容中。 不适用。 必须展开会话堆栈才能从中选择多个消息。

注意

在所有 Outlook 客户端上，不能选择属于不同对话的多个邮件。 如果在展开另一个会话的同时展开另一个会话，则当前展开的对话的视图将折叠并取消选择任何所选邮件。 但是，可以从同一个展开的对话中选择多个邮件，以及不属于任何对话的邮件。

任务窗格固定在多选加载项中

在 Outlook 网页版 和新的 Outlook on Windows 中，打开多选加载项的任务窗格时，会自动将其固定到 Outlook 客户端。 即使用户切换到其他邮件项或从任务窗格中选择 固定 图标，它也会保持固定状态。 只能通过从任务窗格中选择“ 关闭 ”按钮来关闭任务窗格。

相反，在 Outlook on Windows (经典) 和 Mac 中，当用户切换到其他邮件项目时，任务窗格不会自动固定和关闭。

后续步骤

现在，你已使加载项能够对多个所选消息进行操作，可以扩展加载项的功能并进一步增强用户体验。 了解如何将所选消息的项 ID 与服务（如 Microsoft Graph）配合使用来执行更复杂的操作。

另请参阅