Поделиться через

Активация надстройки 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-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 в Windows. Замените существующий элемент скрипта следующей разметкой. Он ссылается на предварительную версию API JavaScript для Office.

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

    Примечание.

    Предварительная версия API JavaScript для Office используется, так как в этом пошаговом руководстве реализованы методы loadItemByIdAsync и unloadAsync , которые в настоящее время находятся в предварительной версии. Если надстройка с несколькими выборами не реализует эти методы, используйте https://appsforoffice.microsoft.com/lib/1.1/hosted/office.js вместо нее. Дополнительные сведения см. в статье Ссылка на библиотеку API JavaScript для Office.

  4. Сохраните изменения.

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

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

  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 , чтобы получить следующие свойства.

    • Логическое вложение
    • Идентификатор беседы
    • Идентификатор сообщения в Интернете
    • Идентификатор элемента
    • Режим элемента (Read или Compose)
    • Тип элемента (Message является единственным поддерживаемым типом в настоящее время)
    • Строка темы

  • Вызовите метод loadItemByIdAsync (предварительная версия), чтобы получить свойства, не предоставленные или выполнить операции с выбранными getSelectedItemsAsync сообщениями. Метод loadItemByIdAsync загружает одно выбранное сообщение за раз с помощью идентификатора веб-служб Exchange (EWS). Чтобы получить идентификаторы EWS выбранных сообщений, рекомендуется вызвать .getSelectedItemsAsync После обработки выбранного сообщения с помощью loadItemByIdAsyncнеобходимо вызвать метод unloadAsync (предварительная версия), прежде чем вызывать loadItemByIdAsync другое выбранное сообщение.

    Совет

    Перед использованием метода определите loadItemByIdAsync , можно ли получить доступ к нужным свойствам с помощью getSelectedItemsAsync. Если это возможно, вам не нужно вызывать loadItemByIdAsync.

В следующем примере реализуются методы getSelectedItemsAsync и loadItemByIdAsync для получения строки темы и адреса электронной почты отправителя из каждого выбранного сообщения.

Примечание.

В loadItemByIdAsync настоящее время метод находится в предварительной версии в классической версии Outlook в Windows. Чтобы просмотреть этот API, установите версию 2405 (сборка 17606.10000) или более позднюю. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите вариант Канал бета-версии .

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

    npm start

    Совет

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

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

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

  4. Выберите Показать область задач. Расположение надстройки зависит от клиента Outlook. Инструкции см. в статье Использование надстроек в Outlook.

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

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

  6. Если вы хотите остановить локальный веб-сервер и удалить надстройку, следуйте применимым инструкциям:

    • Чтобы остановить сервер, выполните следующую команду. Если вы использовали npm start, следующая команда также должна удалить надстройку.

      npm stop

    • Если вы вручную загрузили неопубликованную надстройку, см. статью Удаление неопубликоченной надстройки.

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

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

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

Примечание.

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

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

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

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

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

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

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

Примечание.

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

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

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

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

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

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

См. также