Активация надстроек с помощью событий

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

Обзор

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

1. Обновите манифест, чтобы назначить действие для обработки события.
2. Создайте функцию JavaScript и убедитесь, что она вызывает метод event.completed .
3. Используйте метод Office.actions.associate , чтобы сопоставить функцию действию, указанному в манифесте.

Испытание активации на основе событий

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

Примеры Outlook

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

Примеры работы с Word

• Добавление заголовков при открытии документа

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

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

События Excel, PowerPoint, Word

Каноническое имя события и имя манифеста только для надстройки	Название единого манифеста для Microsoft 365	Описание	Поддерживаемые клиенты и каналы
OnDocumentOpened	Пока не поддерживается`	Происходит, когда пользователь открывает документ или создает новый документ, электронную таблицу или презентацию.	Office в Интернете Office для Windows Office для Mac будет доступен позже

Пример надстройки, которая активируется с помощью этого события, см. в word-add-label-on-open.

Совет

С помощью этого OnDocumentOpened события можно настроить в манифесте надстройку, которая будет выполнять код при открытии любого документа. Эта функция относится к области приложений Office. После установки надстройки администратором Microsoft 365 на портале Администратор клиента Microsoft 365 надстройка запускает и выполняет код для каждого документа Office, открытого в приложениях Office, для поддержки которых надстройка настроена в манифесте. Эта функция отличается от трех похожих функций:

• Надстройка может программно настроить себя на выполнение кода при открытии документа. Этот метод имеет области действия документов, что означает, что его необходимо применять к каждому документу отдельно. Дополнительные сведения см. в статье Настройка документа для запуска кода при его открытии.
• Надстройка может программно настроить документ так, чтобы при открытии документа автоматически открывалась область задач надстройки. Эту функцию также необходимо применять к каждому документу в отдельности. Дополнительные сведения см. в статье "Автоматическое открытие области задач с документом".
• Надстройку можно настроить в манифесте так, чтобы она открывала область задач , когда надстройка устанавливается конечным пользователем. Эта функция ограничена одним документом: тем, который был открыт при установке надстройки. Дополнительные сведения см. в статье "Автоматическое открытие области задач при установке надстройки".

События Outlook

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

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

Примечание.

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

² Надстройки, использующие единый манифест для Microsoft 365, не поддерживаются в Outlook на Mac и на мобильных устройствах. Чтобы сделать вашу надстройку доступной на Mac и мобильных платформах, необходимо создать вторую версию, использующую манифест только надстройки. Дополнительные сведения см. в разделе "Поддержка клиентов и платформ" надстроек Office с единым манифестом приложений для Microsoft 365.

³ Дополнительные сведения см. в статье "Реализация активации на основе событий в надстройках Outlook Mobile".

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

Активация на основе событий в Outlook на мобильных устройствах

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

Поведение и ограничения

При разработке надстройки на основе событий учитывайте поведение и ограничения следующих функций.

• Надстройки на основе событий работают только в том случае, если они развернуты администратором. Если пользователи устанавливают их непосредственно из Microsoft Marketplace или Магазина Office, они не запускаются автоматически (для временного решения ограничения Microsoft Marketplace см. параметры описания Microsoft Marketplace для вашей надстройки на основе событий). Развертывание для администраторов выполняется путем отправки манифеста в Центр администрирования Microsoft 365.

• API, взаимодействующие с пользовательским интерфейсом или отображающие элементы пользовательского интерфейса, не поддерживаются в Word, PowerPoint и Excel. Это вызвано тем, что обработчик событий выполняется в среде выполнения только JavaScript. Дополнительные сведения см. в статье "Среды выполнения в надстройках Office".

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

• Поведение нескольких надстроек, которые подписаны на одно и то же событие, не является детерминированным. Outlook запускает надстройки в произвольном порядке. Для Excel, PowerPoint и Word будет активирована только одна случайная надстройка. Например, если обрабатывается OnDocumentOpenedнесколько надстроек Word, будет запущен только один из этих обработчиков.

• В настоящее время только пять надстроек на основе событий могут активно работать.

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

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

Ограничения для надстроек на основе событий в Excel, PowerPoint, Word и классической версии Outlook для Windows

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

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

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

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

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

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

• В Outlook при создании сообщения, инициированного обратной ссылкой (mailto ссылкой), получение получателей из полей "Кому", "Копия" или "СК" в OnNewMessageCompose обработчике событий может вернуть пустой массив. Это происходит, если Outlook не завершил разрешение адресов электронной почты получателей к моменту OnNewMessageCompose события. Чтобы обойти эту проблему, вместо этого выполняйте проверку получателей в OnMessageRecipientsChanged обработчике событий.

Ограничения надстроек на основе событий в Excel, PowerPoint и Word

Следующие платформы или функции пока не поддерживаются.

• Office для Mac

Ограничения надстроек на основе событий в Outlook в Интернете и в новом Outlook для Windows

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

• Ответ на приглашение на собрание с помощью параметра "Ответить с примечанием ".
• Пересылка собрания из календаря.

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

Некоторые Office.js API, которые изменяют пользовательский интерфейс, не допускаются в обработчиках событий надстроек на основе событий. Ниже приведены заблокированные 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 поддерживается во всех версиях, поддерживающих активацию на основе событий и единый вход (SSO), в то время как 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) в надстройке Office на основе событий или в надстройке для отчетов о спаме.

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

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

Примечание.

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

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

Примечание.

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

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

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

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

Развертывание надстройки

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

• Развертывание, управляемое администратором: надстройка развертывается через Центр администрирования Microsoft 365.
• Ограниченный листинг на Microsoft Marketplace: надстройка опубликована в Microsoft Marketplace, но не отображается в результатах поиска. Для приобретения надстройки требуется URL-адрес кода тестируемой возможности. Чтобы функция активации на основе событий работала, надстройка должна быть развернута администратором.
• Объявление без ограничений на Microsoft Marketplace: надстройка публикуется в Microsoft Marketplace и может осуществляться для поиска пользователями и администраторами по ее имени или идентификатору. Для работы функции активации на основе событий развертывание администратор не требуется. Надстройка должна соответствовать определенным требованиям для неограниченного списка.

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

Приложение Office	Развертывание, управляемое администраторами	Microsoft Marketplace
Excel	Поддерживается	Параметр "Ограниченное размещение"
Outlook	Поддерживается	Параметры ограниченного и неограниченного списка
PowerPoint	Поддерживается	Параметр "Ограниченное размещение"
Word	Поддерживается	Параметр "Ограниченное размещение"

Инструкции по развертыванию надстройки через Центр администрирования Microsoft 365 см. в разделе "Развертывание, управляемое администратором". Дополнительные сведения о размещении надстройки на основе событий в Microsoft Marketplace см. в разделе Параметры размещения надстройки на основе событий в Microsoft Marketplace.

Важно!

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

Развертывание, управляемое администраторами

Развертывание для администраторов выполняется путем отправки манифеста в Центр администрирования Microsoft 365. Для этого выполните следующие действия.

1. На портале администрирования разверните раздел "Параметры " в области навигации и выберите "Интегрированные приложения".

2. На странице "Интегрированные приложения " выберите действие "Отправить пользовательские приложения ".

3. Дальнейшие действия зависят от того, какой манифест используется.

   • Единый манифест для Microsoft 365:

     1. В раскрывающемся списке "Тип приложения " выберите приложение Teams. Это ненадстройка Office!
     2. Используйте элемент управления средством выбора файла, чтобы перейти к ZIP-файлу пакета приложения и выбрать его.
     3. Следуйте инструкциям на странице, чтобы завершить установку.

   • Манифест только для надстроек:

     1. В раскрывающемся списке " Тип приложения " выберите "Надстройка Office".
     2. Используйте элемент управления средством выбора файла, чтобы перейти к манифесту и выбрать его.
     3. Следуйте инструкциям на странице, чтобы завершить установку.

Дополнительные сведения о развертывании надстройки см. в статье "Развертывание и публикация надстроек Office в Центре администрирования Microsoft 365".

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

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

См. также

• Устранение неполадок с надстройками для отчетов о событиях и спаме
• Отладка надстроек для создания отчетов о событиях и спама
• Параметры описания на Microsoft Marketplace для надстройки на основе событий
• Обработка событий OnMessageSend и OnAppointmentSend в надстройке Outlook с помощью интеллектуальных оповещений