Настройка надстройки Outlook для активации на основе событий

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

Примечание.

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

Сведения о том, как реализовать надстройку на основе событий, которая выполняется в Outlook на мобильных устройствах, см. в статье Реализация активации на основе событий в надстройках Outlook mobile.

Поддерживаемые события

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

Каноническое имя события и только имя манифеста надстройки	Унифицированный манифест для имени Microsoft 365	Описание	Минимальный набор требований и поддерживаемые клиенты
OnNewMessageCompose	newMessageComposeCreated	При создании нового сообщения (включая ответить, ответить всем и пересылать), но не при редактировании, например, черновика.	1.10 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac Android2 iOS2
OnNewAppointmentOrganizer	newAppointmentOrganizerCreated	При создании новой встречи, но не при редактировании существующей.	1.10 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnMessageAttachmentsChanged	messageAttachmentsChanged	При добавлении или удалении вложений при создании сообщения. Объект данных, зависящий от события: AttachmentsChangedEventArgs	1.11 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnAppointmentAttachmentsChanged	appointmentAttachmentsChanged	При добавлении или удалении вложений при составлении встречи. Объект данных, зависящий от события: AttachmentsChangedEventArgs	1.11 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnMessageRecipientsChanged	messageRecipientsChanged	При добавлении или удалении получателей при создании сообщения. Объект данных, зависящий от события: RecipientsChangedEventArgs	1.11 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac Android2 iOS2
OnAppointmentAttendeesChanged	appointmentAttendeesChanged	При добавлении или удалении участников во время создания встречи. Объект данных, зависящий от события: RecipientsChangedEventArgs	1.11 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnAppointmentTimeChanged	appointmentTimeChanged	При изменении даты и времени при составлении встречи. Объект данных, зависящий от события: AppointmentTimeChangedEventArgs Важно! При перетаскивании встречи в другой интервал даты и времени в календаре OnAppointmentTimeChanged событие не возникает. Это происходит только в том случае, если дата и время напрямую изменяются по сравнению с встречей.	1.11 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnAppointmentRecurrenceChanged	appointmentRecurrenceChanged	При добавлении, изменении или удалении сведений о повторении при составлении встречи. Если дата и время изменены OnAppointmentTimeChanged , событие также возникает. Объект данных, зависящий от события: RecurrenceChangedEventArgs	1.11 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnInfoBarDismissClicked	infoBarDismissClicked	При отклонении уведомления при создании сообщения или элемента встречи. Будет уведомлена только надстройка, которая добавила уведомление. Объект данных, зависящий от события: InfobarClickedEventArgs	1.11 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnMessageSend	messageSending	При отправке элемента сообщения. Дополнительные сведения см. в пошаговом руководстве по интеллектуальным оповещениям.	1.12 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnAppointmentSend	appointmentSending	При отправке элемента встречи. Дополнительные сведения см. в статье Обработка событий OnMessageSend и OnAppointmentSend в надстройке Outlook с помощью смарт-оповещений.	1.12 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnMessageCompose	messageComposeOpened	При создании нового сообщения (включая ответить, ответить всем и пересылать) или редактировании черновика.	1.12 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnAppointmentOrganizer	appointmentOrganizerOpened	При создании новой встречи или редактировании существующей.	1.12 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnMessageFromChanged	messageFromChanged	При изменении учетной записи почты в поле От создаваемого сообщения. Дополнительные сведения см. в статье Автоматическое обновление подписи при переключении между учетными записями Exchange.	1.13 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnAppointmentFromChanged	appointmentFromChanged	При изменении учетной записи почты в поле организатора создаваемой встречи. Дополнительные сведения см. в статье Автоматическое обновление подписи при переключении между учетными записями Exchange.	1.13 Веб-браузер новый Outlook в Windows Новый пользовательский интерфейс Mac
OnSensitivityLabelChanged	sensitivityLabelChanged	При изменении метки конфиденциальности при составлении сообщения или встречи. Сведения об управлении меткой конфиденциальности почтового элемента см. в статье Управление меткой конфиденциальности сообщения или встречи в режиме создания. Объект данных, зависящий от события: SensitivityLabelChangedEventArgs	1.13 Веб-браузер Windows (новая и классическаяверсии 1) Новый пользовательский интерфейс Mac
OnMessageReadWithCustomAttachment	Недоступно	При открытии сообщения, содержащего определенный тип вложения в режиме чтения.	Предварительная версия3 Windows (классическаяверсия 1)
OnMessageReadWithCustomHeader	Недоступно	При открытии сообщения, содержащего определенное имя заголовка в Интернете в режиме чтения.	Предварительная версия3 Windows (классическаяверсия 1)

Примечание.

¹ Для работы надстроек на основе событий в классической версии Outlook в Windows требуется как минимум Windows 10 версии 1903 (сборка 18362) или Windows Server 2019 версии 1903.

² Outlook на мобильных устройствах поддерживает API до набора обязательных почтовых ящиков 1.5. Однако теперь включена поддержка дополнительных API и функций, представленных в более поздних наборах требований, таких как OnNewMessageCompose событие. Дополнительные сведения см. в статье Реализация активации на основе событий в надстройках Outlook mobile.

³ Для предварительного OnMessageReadWithCustomAttachment просмотра событий и OnMessageReadWithCustomHeader необходимо установить классический Outlook в Windows версии 2312 (сборка 17110.10000) или более поздней. Затем присоединитесь к программе предварительной оценки Microsoft 365 и выберите параметр Канал бета-версии , чтобы получить доступ к бета-сборкам Office.

Устранение неполадок с надстройкой

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

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

Надстройки на основе событий ограничены только развертываниями, управляемыми администратором, даже если они получены из AppSource. Если пользователи получают надстройку из AppSource или магазина Office в приложении, они не смогут активировать функцию надстройки на основе событий. Дополнительные сведения о перечислении надстройки на основе событий в AppSource см. в статье Параметры описания AppSource для надстройки Outlook на основе событий.

Администратор развертывания выполняются путем отправки манифеста в Центр администрирования Microsoft 365. На портале администрирования разверните раздел Параметры в области навигации и выберите Интегрированные приложения. На странице Интегрированные приложения выберите действие Отправить пользовательские приложения .

Важно!

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

Развертывание обновлений манифеста

Так как надстройки на основе событий развертываются администраторами, любое изменение манифеста требует согласия администратора через Центр администрирования Microsoft 365. Пока администратор не примет ваши изменения, пользователи в своей организации не будут использовать надстройку. Дополнительные сведения о процессе предоставления согласия администратора см. в разделе Администратор согласия на установку надстроек на основе событий.

Поведение и ограничения активации на основе событий

Ожидается, что обработчики событий запуска надстроек будут короткими, упрощенными и максимально неактивными. После активации время ожидания надстройки будет истекать в течение примерно 300 секунд, максимально допустимого времени для запуска надстроек на основе событий. Чтобы сообщить о том, что надстройка завершила обработку события запуска, связанный обработчик событий должен вызвать метод event.completed . (Обратите внимание, что код, включенный после инструкции event.completed , не гарантирует выполнение.) При каждом срабатывании события, которое обрабатывает надстройка, надстройка активируется повторно и запускает связанный обработчик событий, а время ожидания сбрасывается. Надстройка заканчивается после того, как истекает время ожидания, или пользователь закрывает окно создания или отправляет элемент.

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

Во всех поддерживаемых клиентах Outlook пользователь должен оставаться в текущем почтовом элементе, где была активирована надстройка, чтобы завершить выполнение. Переход от текущего элемента (например, переход к другому окну создания или вкладке) завершает операцию надстройки. Однако надстройка, активируемая в событии OnMessageSend , обрабатывает переключение элементов по-разному в зависимости от того, на каком клиенте Outlook она работает. Дополнительные сведения см. в разделе "Пользователь удаляется от текущего сообщения" статьи Обработка событий OnMessageSend и OnAppointmentSend в надстройке Outlook с помощью смарт-оповещений.

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

Надстройки на основе событий в классической версии Outlook в Windows

При разработке надстройки на основе событий для запуска в классическом клиенте Outlook для Windows учитывайте следующее:

• Импорт не поддерживается в файле JavaScript, в котором реализуется обработка активации на основе событий.

• Надстройки не выполняют код, включенный в Office.onReady() и Office.initialize. Вместо этого рекомендуется добавить в обработчики событий любую логику запуска, например проверку версии Outlook пользователя.

• Для активации на основе событий поддерживается только файл JavaScript, указанный в манифесте. Необходимо объединить код JavaScript для обработки событий в этот файл. Расположение указанного файла JavaScript в манифесте зависит от типа манифеста, используемого надстройкой.

  • Манифест только надстройки: <переопределение> дочернего <элемента узла среды выполнения>
  • Унифицированный манифест для Microsoft 365: свойство script объекта code

  Обратите внимание, что большой пакет JavaScript может вызвать проблемы с производительностью надстройки. Рекомендуется предварительно обрабатывать тяжелые операции, чтобы они не включались в код обработки событий.

Неподдерживаемые интерфейсы API

Некоторые api Office.js, которые изменяют или изменяют пользовательский интерфейс, не допускаются из надстроек на основе событий. Ниже перечислены заблокированные API.

API	Методы
Office.devicePermission	requestPermissionsAsync
Office.context.auth*	getAccessToken getAccessTokenAsync
Office.context.mailbox	displayAppointmentForm displayMessageForm displayNewAppointmentForm displayNewMessageForm
Office.context.mailbox.item	close
Office.context.ui	displayDialogAsync messageParent

Примечание.

* OfficeRuntime.auth поддерживается во всех версиях Outlook, поддерживающих активацию на основе событий и единый вход, а Office.auth поддерживается только в некоторых сборках Outlook. Дополнительные сведения см. в статье Использование единого входа (SSO) или совместного доступа к ресурсам между источниками (CORS) в надстройке Outlook на основе событий или рассылки нежелательной почты.

Предварительный просмотр функций в обработчиках событий (классический Outlook для Windows)

Классический Outlook для Windows включает локальную копию рабочей и бета-версий Office.js вместо загрузки из сети доставки содержимого (CDN). По умолчанию ссылается на локальную рабочую копию API. Чтобы сослаться на локальную бета-версию API, необходимо настроить реестр компьютера. Это позволит протестировать предварительные версии функций в обработчиках событий в классической версии Outlook в Windows.

1. В реестре перейдите по адресу HKEY_CURRENT_USER\SOFTWARE\Microsoft\Office\16.0\Outlook\Options\WebExt\Developer. Если ключ не существует, создайте его.

2. Создайте запись с именем EnableBetaAPIsInJavaScript и задайте для нее 1значение .

   

Включение единого входа

Чтобы включить единый вход в надстройке на основе событий, необходимо добавить файл JavaScript в хорошо известный URI. Инструкции по настройке этого ресурса см. в статье Использование единого входа (SSO) или совместного доступа к ресурсам между источниками (CORS) в надстройке Outlook на основе событий или рассылки нежелательной почты.

Запрос внешних данных

Внешние данные можно запрашивать с помощью API , например Fetch , или с помощью XMLHttpRequest (XHR) — стандартного веб-API, который отправляет HTTP-запросы для взаимодействия с серверами.

Примечание.

Если надстройка будет работать в среде выполнения, доступной только для JavaScript, используйте абсолютные URL-адреса в вызовах API получения. Относительные URL-адреса в вызовах API fetch не поддерживаются в среде выполнения, доступной только для JavaScript.

Имейте в виду, что при использовании объектов XMLHttpRequest необходимо использовать дополнительные меры безопасности, требуя одну и ту же политику источника и CORS (общий доступ к ресурсам между источниками).

Примечание.

Полная поддержка CORS доступна в клиентах Outlook в Интернете, Mac и Windows (новые и классические (начиная с версии 2201, сборка 16.0.14813.10000).

Чтобы выполнять запросы CORS из надстройки на основе событий, необходимо добавить надстройку и ее файл JavaScript в хорошо известный URI. Инструкции по настройке этого ресурса см. в статье Использование единого входа (SSO) или совместного доступа к ресурсам между источниками (CORS) в надстройке Outlook на основе событий или рассылки нежелательной почты.

См. также

• Устранение неполадок надстроек на основе событий и отчетов о спаме
• Отладка надстроек на основе событий и отчетов о спаме
• Параметры описания AppSource для надстройки Outlook на основе событий
• Обработка событий OnMessageSend и OnAppointmentSend в надстройке Outlook с помощью смарт-оповещений
• Автоматическое определение темы нового сообщения или встречи
• Автоматическое проверка для вложения перед отправкой сообщения
• Автоматическое обновление подписи при переключении между учетными записями почты
• Примеры кода надстроек Office:
  • Шифрование вложений, обработка участников приглашения на собрание и реагирование на изменение даты и времени встречи с помощью активации на основе событий Outlook
  • Настройка подписи с помощью активации на основе событий Outlook
  • Определение и добавление тегов внешних получателей с помощью активации на основе событий Outlook
  • Проверка цветовых категорий сообщения или встречи перед отправкой с помощью смарт-оповещений
  • Проверка метки конфиденциальности сообщения