Реализация закрепляемой области задач в Outlook

  • Статья

Форма пользовательского интерфейса области задач для команд надстройки открывает вертикальную область задач справа от открытого сообщения или приглашения на собрание. Это позволяет надстройке предоставлять пользовательский интерфейс для более подробных взаимодействий, таких как заполнение нескольких текстовых полей. Эта область задач может отображаться в области чтения при просмотре списка сообщений, что позволяет быстро обрабатывать сообщение.

Однако по умолчанию, если пользователь имеет область задач надстройки, открытую для сообщения в области чтения, а затем выбирает новое сообщение, область задач автоматически закрывается. Если надстройка используется часто, пользователь может закрепить эту область, чтобы не активировать ее повторно для каждого сообщения. С помощью закрепляемых областей задач надстройка может предоставить пользователю этот параметр.

Примечание.

Хотя функция закрепляемой области задач появилась в наборе требований 1.5, в настоящее время она доступна только подписчикам Microsoft 365, используя следующие возможности:

  • Современная версия Outlook в Интернете
  • Новый Outlook в Windows (предварительная версия)
  • Классическая Outlook 2016 или более поздней версии в Windows (сборка 7668.2000 или более поздней версии для пользователей в текущих каналах или каналах предварительной оценки Microsoft 365, сборка 7900.xxxx или более поздней версии для пользователей в отложенных каналах)
  • Outlook на Mac (версия 16.13.503 или более поздняя)

Важно!

Закрепленные области задач недоступны для следующих компонентов:

  • Встречи и собрания
  • Outlook.com

Поддержка закрепления области задач

Для начала нужно добавить поддержку закрепления в манифест надстройки. Разметка зависит от типа манифеста, используемого надстройкой.

Добавьте свойство pinnable, задается значением true, к объекту в массиве actions, который определяет кнопку или пункт меню, открывающий область задач. Ниже приведен пример.

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

Полный пример: элемент управления msgReadOpenPaneButton в примере манифеста command-demo.

Примечание.

Закрепление области задач автоматически поддерживается в надстройке, которая активируется без включения области чтения или первого выбранного сообщения. Дополнительные сведения см. в статье Активация надстройки Outlook без включения области чтения или выбранного сообщения.

Обновление пользовательского интерфейса на основе выбранного сообщения

Чтобы обновлять пользовательский интерфейс или внутренние переменные области задач на основе текущего элемента, необходимо зарегистрировать обработчик событий, чтобы получать уведомления об изменении.

Реализация обработчика событий

Обработчик событий должен принимать один параметр, а именно — объектный литерал. Для свойства 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 в Windows (предварительная версия) при открытии области задач надстройки, реализующей функцию множественного выбора элементов, она автоматически закрепляется в клиенте Outlook. Он остается закрепленным, даже если пользователь переключается на другой почтовый элемент или выбирает значок закрепления в области задач. Область задач можно закрыть, только нажав кнопку Закрыть в области задач.

И наоборот, в классических Outlook для Windows и Outlook на Mac область задач надстройки с несколькими выборами не закрепляется автоматически и закрывается при переключе пользователем на другой почтовый элемент.

Развертывание для пользователей

Если вы планируете опубликовать надстройку Outlook в AppSource и она настроена с помощью закрепляемой области задач, содержимое надстройки не должно быть статическим и четко отображать данные, связанные с открытым или выбранным в почтовом ящике сообщением. Это гарантирует, что надстройка пройдет проверку AppSource.

См. также

Пример надстройки, в которой реализована закрепляемая область задач, на сайте GitHub: command-demo.