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

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

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

Обзор

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

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

Попробуйте активацию на основе событий

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

Примеры Outlook

примеры Word

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

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

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

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

События 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
  • Веб-браузер4
  • Windows (новыеверсии 4 и классическиеверсии 1)
  • Новый пользовательский интерфейс Mac2
  • Android23
  • iOS23
OnAppointmentFromChanged appointmentFromChanged При изменении учетной записи почты в поле организатора создаваемой встречи. Дополнительные сведения см. в статье Автоматическое обновление подписи при переключении между учетными записями Exchange. 1.13
  • Новый пользовательский интерфейс Mac2
OnSensitivityLabelChanged sensitivityLabelChanged При изменении метки конфиденциальности при составлении сообщения или встречи. Сведения об управлении меткой конфиденциальности почтового элемента см. в статье Управление меткой конфиденциальности сообщения или встречи в режиме создания.

Объект данных, зависящий от события: SensitivityLabelChangedEventArgs		 1.13
  • Веб-браузер4
  • Windows (новыеверсии 4 и классическиеверсии 1)
  • Новый пользовательский интерфейс Mac2
OnMessageReadWithCustomAttachment Недоступно При открытии сообщения, содержащего определенный тип вложения в режиме чтения. Предварительная версия5
  • Windows (классическаяверсия 1)
OnMessageReadWithCustomHeader Недоступно При открытии сообщения, содержащего определенное имя заголовка в Интернете в режиме чтения. Предварительная версия5
  • Windows (классическаяверсия 1)
OnMessageRead (предварительная версия) Недоступно При сопоставлении заголовка зашифрованного сообщения с ключом заголовка в манифесте надстройки. Дополнительные сведения см. в статье Создание надстройки Outlook для шифрования. Предварительный просмотр
  • Windows (классическаяверсия 1)

Примечание.

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

2 Надстройки, использующие унифицированный манифест для Microsoft 365, не поддерживаются непосредственно в Outlook на Mac и на мобильных устройствах. Чтобы запустить надстройку этого типа на Mac и на мобильных платформах, ее необходимо сначала опубликовать в Microsoft Marketplace, а затем развернуть в Центре Microsoft 365 Admin. Дополнительные сведения см. в разделе "Поддержка клиентов и платформ" статьи Надстройки Office с манифестом унифицированного приложения для Microsoft 365.

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

4 События OnMessageFromChanged и OnSensitivityLabelChanged в настоящее время недоступны в едином манифесте Microsoft 365 в Outlook в Интернете и новом Outlook в Windows. Для обработки этих событий реализуйте манифест только надстройки. Сведения о типах манифестов см. в разделе Манифест надстроек Office.

5 Для предварительного 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 в Windows. Это связано с тем, что обработчик событий выполняется в среде выполнения, доступной только для JavaScript. Дополнительные сведения см. в разделе Среды выполнения в надстройках Office.

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

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

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

  • Во всех поддерживаемых клиентах 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 не выполняется. Мы рекомендуем добавить в обработчики событий любую логику запуска, необходимую обработчикам событий, например проверку версии клиента пользователя.

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

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

  • Office для Mac
  • Унифицированный манифест для Microsoft 365

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

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

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

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

    Параметр реестра EnableBetaAPIsInJavaScript имеет значение 1.

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

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

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

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

Примечание.

Если надстройка будет работать в среде выполнения, доступной только для JavaScript, используйте абсолютные URL-адреса в вызовах API получения. Относительные 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. На странице Интегрированные приложения выберите действие Отправить пользовательские приложения .

Страница Интегрированные приложения на Центр администрирования Microsoft 365 с выделенным действием Отправить пользовательские приложения.

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

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

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

См. также

  • Last updated on