通过

在多条消息上激活 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-l">Get information about each selected message</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">Get information</span>
    </div>
</main>

  3. 仅适用于经典 Outlook on Windows。 将现有 脚本 元素替换为以下标记。 这会引用 Office JavaScript API 的预览版。

    <script type="text/javascript" src="https://appsforoffice.microsoft.com/lib/beta/hosted/office.js"></script>

    注意

    之所以使用 Office JavaScript API 的预览版本，是因为本演练实现了 loadItemByIdAsync 和 unloadAsync 方法，这些方法目前处于预览状态。 如果多选加载项未实现这些方法，请改用 https://appsforoffice.microsoft.com/lib/1/hosted/office.js 。 有关详细信息，请参阅 引用 Office JavaScript API 库。

  4. 保存所做的更改。

实现 SelectedItemsChanged 事件的处理程序

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

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

  2. 将 Office.onReady() 函数替换为以下内容：

    let list;

Office.onReady((info) => {
  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;
    list = document.getElementById("selected-items");

    // 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.");
    });
  }
});

  3. 保存所做的更改。

获取属性并针对所选消息运行操作

注册事件处理程序后，加载项现在可以获取属性或对多个所选消息运行操作。 有两种方法可以处理所选消息。 每个选项的用法取决于方案所需的属性和操作。

  • 调用 getSelectedItemsAsync 方法以获取以下属性。

    • 附件布尔值
    • 对话 ID
    • Internet 消息 ID
    • 项目 ID
    • 项模式 (Read 或 Compose)
    • 项类型 (Message 是目前唯一受支持的类型)
    • 主题行

  • 调用 loadItemByIdAsync 方法 (预览) 以获取未提供 getSelectedItemsAsync 的属性或对所选消息运行操作。 方法 loadItemByIdAsync 使用邮件的 Exchange Web Services (EWS) ID 一次加载一封所选邮件。 若要获取所选消息的 EWS ID，建议调用 getSelectedItemsAsync。 使用 loadItemByIdAsync处理所选消息后，必须调用 unloadAsync 方法 (预览) ，然后再调用 loadItemByIdAsync 另一条所选消息。

    提示

    在使用 loadItemByIdAsync 方法之前，请确定是否已经可以使用 访问所需的 getSelectedItemsAsync属性。 如果可以，则无需调用 loadItemByIdAsync。

以下示例实现 getSelectedItemsAsync 和 loadItemByIdAsync 方法，以便从每封所选邮件中获取主题行和发件人的电子邮件地址。

注意

此方法 loadItemByIdAsync 目前在经典 Outlook on Windows 中处于预览状态。 若要预览此 API，请安装版本 2405 (内部版本 17606.10000) 或更高版本。 然后，加入 Microsoft 365 预览体验计划 ，然后选择 “Beta 频道 ”选项。

  1. 在 taskpane.js中，将现有 run 函数替换为以下代码。

    export async function run() {
  // Clear the list of previously selected messages, if any.
  clearList(list);

  // Get the subject line and sender's email address of each selected message 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;
    }

    const selectedItems = asyncResult.value;
    getItemInfo(selectedItems);
  });
}

// Gets the subject line and sender's email address of each selected message.
async function getItemInfo(selectedItems) {
  for (const item of selectedItems) {
    addToList(item.subject);
    // The loadItemByIdAsync method is currently only available to preview in classic Outlook on Windows.
    if (Office.context.diagnostics.platform === Office.PlatformType.PC) {
      await getSenderEmailAddress(item);
    }
  }
}

// Gets the sender's email address of each selected message.
async function getSenderEmailAddress(item) {
  const itemId = item.itemId;
  await new Promise((resolve) => {
    Office.context.mailbox.loadItemByIdAsync(itemId, (result) => {
      if (result.status === Office.AsyncResultStatus.Failed) {
        console.log(result.error.message);
        return;
      }

      const loadedItem = result.value;
      const sender = loadedItem.from.emailAddress;
      appendToListItem(sender);

      // Unload the current message before processing another selected message.
      loadedItem.unloadAsync((asyncResult) => {
        if (asyncResult.status === Office.AsyncResultStatus.Failed) {
          console.log(asyncResult.error.message);
          return;
        }

        resolve();
      });
    });
  });
}

// Clears the list in the task pane.
function clearList(list) {
  while (list.firstChild) {
    list.removeChild(list.firstChild);
  }
}

// Adds an item to a list in the task pane.
function addToList(item) {
  const listItem = document.createElement("li");
  listItem.textContent = item;
  list.appendChild(listItem);
}

// Appends data to the last item of the list in the task pane.
function appendToListItem(data) {
  const listItem = list.lastChild;
  listItem.textContent += ` (${data})`;
}

  2. 保存所做的更改。

试用

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

    npm start

    提示

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

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

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

  4. 选择“ 显示任务窗格”。 加载项的位置因 Outlook 客户端而异。 有关指导，请参阅 在 Outlook 中使用加载项。

  5. 在任务窗格中，选择“ 获取信息”。 任务窗格中会显示所选邮件的主题行和发件人电子邮件地址的列表。

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

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

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

      npm stop

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

项多选行为和限制

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

  • 必须一次从一个 Exchange 邮箱中选择邮件。 不支持非 Exchange 邮箱。
  • 必须一次从一个邮箱文件夹中选择邮件。 如果加载项位于不同的文件夹中，则外接程序不会在多个邮件上激活，除非启用了“对话”视图。 有关详细信息，请参阅 对话中的多选。
  • 加载项必须实现任务窗格才能检测 SelectedItemsChanged 事件。
  • 必须启用 Outlook 中的 阅读窗格 。 这种情况的一个例外是，如果通过清单中的无项上下文功能启用项多选功能。 若要了解详细信息，请参阅 在未启用阅读窗格或未选择邮件的情况下激活 Outlook 加载项。
  • 一次最多可以选择 100 条消息。
  • 方法 loadItemByIdAsync 一次只处理一条选定的消息。 请记得在处理完消息后loadItemByIdAsync调用 unloadAsync 。 这样，加载项就可以加载和处理下一条所选消息。
  • 通常，只能对使用 loadItemByIdAsync 方法加载的所选消息运行 get 操作。 但是，管理已加载消息的 类别 是一个例外。 可以从加载的消息中添加、获取和删除类别。
  • loadItemByIdAsync任务窗格和函数命令加载项支持 方法。基于事件的激活加载项不支持此方法。

注意

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

对话中的多选

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

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

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

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

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

注意

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

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

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

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

后续步骤

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

另请参阅