在 Outlook 中实现可固定的任务窗格

  • 项目

外接程序命令 的任务窗格 UX 形状会在打开的邮件或会议请求右侧打开垂直任务窗格。 这允许加载项为更详细的交互提供 UI，例如填写多个文本字段。 查看消息列表时，可以在阅读窗格中显示此任务窗格，以便快速处理消息。

但是，默认情况下，如果用户在阅读窗格中为邮件打开了加载项任务窗格，然后选择新邮件，则任务窗格会自动关闭。 如果频繁使用外接程序，用户可能更倾向于让此任务窗格一直处于打开状态，这样就无需重新激活每个邮件的外接程序了。 使用可固定的任务窗格，加载项可以为用户提供该选项。

注意

尽管可固定任务窗格功能已在 要求集 1.5 中引入，但目前仅对使用以下项的 Microsoft 365 订阅者可用：

  • 新式 Outlook 网页版
  • 新 Outlook on Windows (预览版)
  • Windows (内部版本 7668.2000 或更高版本上的经典Outlook 2016或更高版本，适用于当前频道或 Microsoft 365 预览体验成员频道、内部版本 7900.xxxx 或更高版本的用户)
  • Mac 版 Outlook (版本 16.13.503 或更高版本)

重要

可固定任务窗格不适用于以下各项：

  • 约会/会议
  • Outlook.com

支持固定任务窗格

第一步是添加固定支持，此步操作是在外接程序清单中完成。 标记因外接程序使用的清单类型而异。

将设置为 的“固定”属性 true添加到定义打开任务窗格的按钮或菜单项的“actions”数组中的 对象。 示例如下。

"actions": [
    {
        "id": "OpenTaskPane",
        "type": "openPage",
        "view": "TaskPaneView",
        "displayName": "OpenTaskPane",
        "pinnable": true
    }
]

有关完整示例，请参阅command-demo 示例清单中的 msgReadOpenPaneButton 控件。

注意

在未启用阅读窗格或先选择消息的情况下激活的加载项中自动支持任务窗格固定。 若要了解详细信息，请参阅 在未启用阅读窗格或未选择邮件的情况下激活 Outlook 加载项。

根据当前选择的邮件处理 UI 更新

若要根据当前项更新任务窗格的 UI 或内部变量，必须注册事件处理程序，才能收到变化通知。

实现事件处理程序

事件处理程序应接受一个参数，即对象文本。 该对象的 type 属性将设为 Office.EventType.ItemChanged。 事件调用后，Office.context.mailbox.item 对象已更新，以反映当前选定项。

function itemChanged(eventArgs) {
  // Update UI based on the new current item.
  updateTaskPaneUI(Office.context.mailbox.item);
}

重要

ItemChanged 事件的事件处理程序的实现应检查 Office.content.mailbox.item 是否为 NULL。

// Example implementation.
function updateTaskPaneUI(item) {
  // Assuming that item is always a read item (instead of a compose item).
  if (item != null) console.log(item.subject);
}

注册事件处理程序

使用 Office.context.mailbox.addHandlerAsync 方法注册 Office.EventType.ItemChanged 事件的事件处理程序。 这应在任务窗格的 函数中 Office.onReady 完成。

Office.onReady(() => {
  $(document).ready(() => {
    // Set up the ItemChanged event.
    Office.context.mailbox.addHandlerAsync(Office.EventType.ItemChanged, itemChanged);
    updateTaskPaneUI(Office.context.mailbox.item);
  });
});

在多选中固定任务窗格

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

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

部署到用户

如果计划将 Outlook 外接程序 发布到AppSource，并且它配置了可固定的任务窗格，则外接程序内容不得是静态的，并且必须清楚地显示与邮箱中打开或选择的邮件相关的数据。 这可确保加载项通过 AppSource 验证。

另请参阅

有关实现可固定的任务窗格的示例外接程序，请参阅 GitHub 上的 command-demo。