Объекты событий

На этой странице описана структура объектов событий надстроек Google Workspace.

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

Дополнения Google Workspace используют объекты событий в следующих местах:

• Триггеры на главной странице . Каждой определяемой вами функции homepageTrigger автоматически передается объект события при срабатывании триггерной функции домашней страницы. Вы можете использовать этот объект в триггерной функции своей домашней страницы, чтобы идентифицировать активное хост-приложение, платформу клиента, языковой стандарт пользователя и другую информацию.

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

• Контекстуальные триггеры . Каждое хост-приложение предоставляет свой набор контекстных триггеров, которые срабатывают, когда пользователь входит в определенный контекст. Например:

  • Gmail предоставляет контекстный триггер, когда пользователь открывает сообщение , и другой, когда пользователь составляет сообщение .
  • Календарь Google предоставляет контекстный триггер, когда пользователь открывает событие .
  • Google Диск предоставляет контекстный триггер, когда пользователь выбирает файлы на Диске .

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

• Действия виджета . Объекты событий также используются для обеспечения интерактивности виджетов , используя ту же модель действий , которую используют надстройки Gmail. Дополнения Google Workspace используют все те же функции обработчиков виджетов, объекты Action и ответы на действия. Однако в надстройках Google Workspace объекты событий действий содержат еще больше информации, на которую может действовать функция обратного вызова.

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

• Ссылка на предварительный просмотр срабатывает . В Документах, Таблицах и Презентациях Google вы можете настроить предварительный просмотр ссылок для сторонних сервисов на основе определенных шаблонов URL-адресов. Когда пользователи взаимодействуют со ссылкой, соответствующей шаблону, срабатывает linkPreviewTriggers , и объект события, содержащий ссылку, передается в функцию обратного вызова триггера. Ваша надстройка может использовать этот объект события для создания смарт-чипа и карты, которые отображают информацию о ссылке в главном приложении. Вы также можете создавать действия виджета, чтобы пользователи могли взаимодействовать с карточкой предварительного просмотра и ее содержимым.

Структура объекта события

В следующей таблице описана структура верхнего уровня объектов событий надстроек Google Workspace. Структура объекта события включает поле верхнего уровня commonEventObject для информации, независимой от хоста. Каждый объект события также может иметь одно из следующих полей верхнего уровня, зависящих от хоста, определяемых активным хост-приложением: gmailEventObject , calendarEventObject или driveEventObject .

В целях обратной совместимости объекты событий надстроек Google Workspace также включают все исходные поля, используемые в объектах событий действий надстроек Gmail . Эти поля перечислены в таблице ниже в разделе «Исходные поля надстройки Gmail»; информация в этих полях воспроизводится в новой структуре объекта.

Общий объект события

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

Помимо домашней страницы и контекстных триггеров, надстройки создают и передают объекты событий функциям обратного вызова действий , когда пользователь взаимодействует с виджетами. Функция обратного вызова вашего дополнения может запрашивать общий объект события, чтобы определить содержимое открытых виджетов в клиенте пользователя. Например, ваша надстройка может найти текст, который пользователь ввел в виджет TextInput , в объекте eventObject.commentEventObject.formInputs .

Входные данные формы выбора даты и времени

Функции обратного вызова действий могут получать текущие значения виджета в поле commonEventObject.formInputs . Сюда входят выбранные пользователем значения даты и времени в виджетах выбора даты или времени. Однако структура информации различается в зависимости от того, был ли виджет настроен как средство выбора даты и времени, средство выбора только даты или средство выбора только времени. Структурные различия описаны в следующей таблице:

Объект события календаря

Объект события «Календарь» — это часть общего объекта события, содержащая информацию о календаре пользователя и событиях календаря. Он присутствует в объекте события только в том случае, если хост-приложением является Календарь Google.

В следующей таблице перечислены поля, присутствующие в поле calendarEventObject объекта события. Поля, помеченные как «Созданные пользователем данные», присутствуют в объекте события тогда и только тогда, когда данные присутствуют в событии «Календарь» и надстройка устанавливает для поля манифеста addOns.calendar.currentEventAccess значение READ или READ_WRITE .

Посетитель

Объекты Attendee содержат информацию об отдельных участниках событий Календаря Google. Эта информация присутствует в объекте события тогда и только тогда, когда данные присутствуют в событии Calendar и надстройка устанавливает для поля манифеста addOns.calendar.currentEventAccess значение READ или READ_WRITE .

Данные конференции

Объекты данных конференции содержат информацию о конференциях, прикрепленных к событиям Календаря Google. Это могут быть решения для конференций Google, такие как Google Meet, или сторонние конференции. Эта информация присутствует в объекте события тогда и только тогда, когда данные присутствуют в событии Calendar и надстройка устанавливает для поля манифеста addOns.calendar.currentEventAccess значение READ или READ_WRITE .

Точка входа

Объекты точек входа несут информацию об установленных средствах доступа к данной конференции, например по телефону или видео. Эта информация присутствует в объекте события тогда и только тогда, когда данные присутствуют в событии Calendar и надстройка устанавливает для поля манифеста addOns.calendar.currentEventAccess значение READ или READ_WRITE .

Объект события Диска

Объект события Диска — это часть общего объекта события, которая содержит информацию о Google Диске пользователя и его содержимом. Он присутствует в объекте события только в том случае, если хост-приложением является Google Диск.

Объект на Диске

Объекты элементов Диска содержат информацию об определенных элементах Диска, таких как файлы или папки.

Объект события Gmail

Объект события Gmail — это часть общего объекта события, содержащая информацию о сообщениях Gmail пользователя. Он присутствует в объекте события только в том случае, если хост-приложением является Gmail.

Объект события Документов

Объект события «Документы» — это часть общего объекта события, которая содержит информацию о документе пользователя и его содержимом. Он присутствует в объекте события только в том случае, если хост-приложением является Google Docs.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Объект события Таблиц

Объект события Sheets — это часть общего объекта события, которая содержит информацию о документе пользователя и его содержимом. Он присутствует в объекте события только в том случае, если ведущим приложением является Google Таблицы.

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Объект события слайдов

Объект события «Слайды» — это часть общего объекта события, которая содержит информацию о документе пользователя и его содержимом. Он присутствует в объекте события только в том случае, если ведущим приложением является Google Slides.

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}