Активация надстройки Outlook для нескольких сообщений

  • Статья

С помощью функции множественного выбора элементов надстройка Outlook теперь может активировать и выполнять операции с несколькими выбранными сообщениями за один раз. Некоторые операции, такие как отправка сообщений в систему управления отношениями с клиентами (CRM) или классификация многочисленных элементов, теперь можно легко выполнить одним щелчком мыши.

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

Примечание.

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

Настройка среды

Выполните краткое руководство по созданию проекта надстройки с помощью генератора Yeoman для надстроек Office.

Настройка манифеста

  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, идентификатор которого имеет значение CommandsRuntime.

  6. В массиве extensions.ribbons.tabs.controls удалите второй объект, идентификатор которого — 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

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

  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 также можно использовать для получения других свойств сообщения, таких как идентификатор элемента, тип элемента (Message является единственным поддерживаемым типом в настоящее время) и режим элемента (Read или Compose).

Примечание.

Дополнительные свойства сообщения, такие как conversationId, internetMessageIdи hasAttachment, доступны в предварительной версии в Outlook в Windows. Чтобы просмотреть эти свойства, необходимо установить версию 2305 (сборка 16501.20210) или более позднюю. Дополнительные сведения об этих свойствах см. в статье Office.SelectedItemDetails.

  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. В терминале выполните следующий код в корневом каталоге проекта. Это запустит локальный веб-сервер и загрузит неопубликованную надстройку.

    npm start

    Совет

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

  2. В Outlook убедитесь, что область чтения включена. Сведения о включении области чтения см. в статье Использование и настройка области чтения для предварительного просмотра сообщений.

  3. Перейдите в папку "Входящие" и выберите несколько сообщений, удерживая нажатой клавишу CTRL при выборе сообщений.

  4. Выберите Показать область задач на ленте.

  5. В области задач выберите Выполнить , чтобы просмотреть список строк темы выбранных сообщений.

    Пример списка строк темы, полученных из нескольких выбранных сообщений.

Поведение и ограничения множественного выбора элементов

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

  • Сообщения должны быть выбраны из одного почтового ящика Exchange одновременно. Почтовые ящики, отличные от Exchange, не поддерживаются.
  • Сообщения должны быть выбраны из одной папки почтового ящика одновременно. Надстройка не активируется для нескольких сообщений, если они находятся в разных папках, если не включено представление Беседы. Дополнительные сведения см. в разделе Множественный выбор в беседах.
  • Надстройка должна реализовать область задач, чтобы обнаружить SelectedItemsChanged событие.
  • Область чтения в Outlook должна быть включена. Исключением является, если функция множественного выбора элементов включена через функцию контекста без элемента в манифесте. Дополнительные сведения см. в статье Активация надстройки Outlook без включения области чтения или выбранного сообщения.
  • Одновременно можно выбрать не более 100 сообщений.

Примечание.

Приглашения на собрания и ответы считаются сообщениями, а не встречами и поэтому могут быть включены в выбор.

Множественный выбор в беседах

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

Selection Расширенное представление беседы Свернутая беседа
Выбран заголовок беседы Если заголовок беседы является единственным выбранным элементом, надстройка с поддержкой множественного выбора не активируется. Однако если также выбраны другие сообщения, не относящиеся к заголовку, надстройка будет активирована только для них, а не для выбранного заголовка. Поведение зависит от клиента Outlook.

Outlook в Windows и mac:
В выбор сообщения включается новейшее сообщение (то есть первое сообщение в стеке бесед).

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

Outlook в Интернете и новый Outlook в Windows (предварительная версия):
Выбраны все сообщения в стеке бесед. Сюда входят сообщения в беседе, которые находятся в папках, отличных от текущего представления.
Несколько выбранных сообщений в стеке бесед находятся в той же папке, что и в настоящее время в представлении. Все выбранные сообщения в одной беседе включаются в выборку. Не применимо. Необходимо развернуть стек бесед, чтобы выбрать несколько сообщений из него.
Несколько выбранных сообщений в стеке бесед находятся в разных папках, отличных от текущего в представлении Все выбранные сообщения в одной беседе включаются в выборку. Не применимо. Необходимо развернуть стек бесед, чтобы выбрать несколько сообщений из него.

Примечание.

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

Закрепление области задач в надстройках с несколькими выборками

В Outlook в Интернете и в новом Outlook в Windows (предварительная версия) при открытии области задач надстройки с несколькими выборами она автоматически закрепляется в клиенте Outlook. Он остается закрепленным, даже если пользователь переключается на другой почтовый элемент или выбирает значок закрепления в области задач. Область задач можно закрыть, только нажав кнопку Закрыть в области задач.

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

Дальнейшие действия

Теперь, когда вы включили надстройку для работы с несколькими выбранными сообщениями, вы можете расширить возможности надстройки и улучшить пользовательский интерфейс. Изучите выполнение более сложных операций с помощью идентификаторов элементов выбранных сообщений с такими службами, как Веб-службы Exchange (EWS) и Microsoft Graph.

См. также