Дополнительные действия

Дополнительные действия обеспечивают интерактивное поведение виджетов . Создав действие, вы определяете, что происходит, когда пользователь выбирает или обновляет виджет.

В большинстве случаев вы можете определить дополнительные действия, используя объекты Action , предоставляемые сервисом Google Apps Script Card . Каждое Action связывается с функцией обратного вызова при его создании. Вы реализуете функцию обратного вызова для выполнения выбранных шагов при взаимодействии пользователя с виджетом. Вы также должны связать Action с виджетом, используя соответствующую функцию обработчика виджета , которая определяет, какой тип взаимодействия запускает функцию обратного вызова Action .

Настройте виджет с помощью Action , используя следующий процесс:

1. Создайте объект Action , указав функцию обратного вызова, которую он должен выполнить, а также все необходимые параметры.
2. Вызовите соответствующую функцию обработчика виджета , используя объект Action .
3. Реализуйте функцию обратного вызова для выполнения требуемого действия.

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

Функции обработчика виджетов

Для привязки виджета к Action или другому поведению используйте функцию обработчика виджета. Функция обработчика определяет, какой тип взаимодействия (например, щелчок по виджету или редактирование текстового поля) запускает действие. Функция обработчика также определяет, какие шаги, если таковые имеются, предпринимает пользовательский интерфейс после завершения действия.

В таблице ниже перечислены различные типы обработчиков для виджетов и виджеты, с которыми они используются:

Функция обработчика	Запускает действие	Применимые виджеты	Описание
setOnChangeAction	Значение виджета изменяется	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	Задает Action , которое выполняет функцию Apps Script, когда виджет теряет фокус, например, когда пользователь вводит текст в поле ввода и нажимает Enter. Обработчик автоматически передает объект события вызываемой функции. При выборе этого параметра в объект события можно добавить дополнительную информацию о параметрах.
setOnClickAction	Пользователь нажимает на виджет.	CardAction Image ImageButton DecoratedText TextButton	Задает Action , которое выполняет функцию Apps Script при щелчке пользователя по виджету. Обработчик автоматически передает объект события вызываемой функции. В этот объект события можно добавить необязательную информацию о параметрах.
setComposeAction	Пользователь нажимает на виджет.	CardAction Image ImageButton DecoratedText TextButton	Специфично для Gmail. Задает Action , которое создает черновик электронного письма, а затем отображает его пользователю в окне создания сообщения в пользовательском интерфейсе Gmail. Вы можете создать черновик как новое сообщение или как ответ на открытое сообщение в Gmail. Когда обработчик вызывает функцию обратного вызова для создания черновика, он передает объект события в эту функцию. Дополнительные сведения см. в разделе «Создание черновиков» .
setOnClickOpenLinkAction	Пользователь нажимает на виджет.	CardAction Image ImageButton DecoratedText TextButton	Задает Action , которое откроет URL-адрес при щелчке пользователя по виджету. Используйте этот обработчик, если необходимо сформировать URL-адрес или выполнить другие действия до открытия ссылки; в противном случае обычно проще использовать setOpenLink . Вы можете открыть URL-адрес только в новом окне. При закрытии вы можете вызвать перезагрузку пользовательского интерфейса дополнения.
setOpenLink	Пользователь нажимает на виджет.	CardAction Image ImageButton DecoratedText TextButton	Этот обработчик открывает URL-адрес непосредственно при щелчке пользователя по виджету. Используйте его, если вам известен URL-адрес и вам нужно только открыть его; в противном случае используйте setOnClickOpenLinkAction . Вы можете открыть URL-адрес в новом окне или во всплывающем окне. При закрытии вы можете вызвать перезагрузку пользовательского интерфейса дополнения.
setSuggestionsAction	Пользователь вводит текст в поле ввода.	TextInput	Задает Action , которое выполняет функцию Apps Script, когда пользователь вводит текст в текстовое поле ввода. Обработчик автоматически передает объект события вызываемой функции. Дополнительные сведения см. в разделе «Подсказки автозаполнения для текстовых полей ввода» .

функции обратного вызова

Функции обратного вызова выполняются при срабатывании Action . Поскольку функции обратного вызова являются функциями Apps Script, вы можете назначить им практически любые функции скрипта.

Внимание: служба Apps Script Card ограничивает время выполнения функций обратного вызова максимум 30 секундами. Если выполнение займет больше времени, пользовательский интерфейс вашего дополнения может некорректно обновлять отображение карточки в ответ на Action .

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

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

Предпринятые действия	Функция обратного вызова должна возвращать
Навигация	ActionResponse
Отобразить Notification	ActionResponse
Откройте ссылку с помощью setOnClickOpenLinkAction	ActionResponse
Отображать подсказки автозаполнения	SuggestionResponse
Используйте универсальное действие	UniversalActionResponse
Другие действия	Ничего

Действия для приложений, размещенных в Google Workspace.

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

• Действия календаря
• Действия в чате
• Действия во время вождения
• Действия Gmail
• Действия редактора

При использовании классов построения ответов вызовите метод build для создания объектов ответов. В противном случае возникнет ошибка.

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

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

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

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

Полное описание структуры объекта события см. в разделе «Объекты событий».

В дополнениях Gmail использовалась упрощенная версия этой структуры объекта события, которая теперь устарела. Для обеспечения обратной совместимости все поля исходного объекта события дополнений Gmail по-прежнему содержатся в новой структуре объекта события (см. структуру объекта события ). Однако та же информация воспроизводится в подструктурах commonEventObject и объекта события Gmail . Если вы обновляете дополнение Gmail до дополнения Google Workspace, измените свой код, чтобы использовать обновленные поля объекта события. В конечном итоге исходные поля объекта события Gmail будут удалены.