Действия дополнений позволяют виджетам взаимодействовать с пользователем. Создав действие, вы определяете, что произойдет, когда пользователь выберет или обновит виджет.
В большинстве случаев действия дополнений можно задать с помощью объектов Action, предоставляемых сервисом карт Google Apps Script.
Каждое значение Action при создании связывается с функцией обратного вызова. Вы реализуете функцию обратного вызова, чтобы выполнять определенные действия, когда пользователь взаимодействует с виджетом. Кроме того, вам нужно связать Action с виджетом, используя подходящую функцию обработчика виджета, которая определяет, какое взаимодействие вызывает обратный вызов Action.
Чтобы настроить виджет с Action, выполните следующие действия:
- Создайте объект
Action, указав функцию обратного вызова, которую он должен выполнить, а также все необходимые ей параметры. - Вызовите подходящую функцию обработчика виджета для виджета, используя объект
Action. - Реализуйте функцию обратного вызова, чтобы задать нужное поведение.
Не путайте объекты Action с объектами CardAction. Объекты CardAction – это пункты меню в заголовке карточки, а объекты Action определяют ответы на действия пользователя в интерфейсе.
Функции обработчика виджетов
Чтобы связать виджет с Action или другим действием, используйте функцию обработчика виджетов. Функция обработчика определяет, какое взаимодействие (например, нажатие на виджет или редактирование текстового поля) запускает действие. Функция обработчика также определяет, какие действия должен выполнить интерфейс после завершения действия.
В таблице ниже перечислены различные типы обработчиков для виджетов и указано, с какими виджетами они используются.
| Функция обработчика | Запускает действие | Подходящие виджеты | Описание |
|---|---|---|---|
setOnChangeAction |
Значение виджета меняется. |
DatePicker
DateTimePicker
SelectionInputSwitch
TextInput
TimePicker
|
Задает Action, которая выполняет функцию Apps Script, когда виджет теряет фокус, например когда пользователь вводит текст в поле ввода и нажимает клавишу Ввод. Обработчик автоматически передает объект события функции, которую он вызывает.
Если вы выберете этот вариант, то сможете добавить в объект события дополнительную информацию о параметрах. |
setOnClickAction |
Пользователь нажимает на виджет. |
CardActionImageImageButtonDecoratedTextTextButton
|
Задает Action, который выполняет функцию Apps Script, когда пользователь нажимает на виджет. Обработчик автоматически передает объект события вызываемой функции.
В этот объект события можно добавить информацию о необязательных параметрах. |
setComposeAction |
Пользователь нажимает на виджет. |
CardActionImageImageButtonDecoratedTextTextButton
|
Для Gmail. Задает
Action
, который создает черновик письма, а затем показывает его пользователю в окне создания письма в интерфейсе Gmail. Вы можете создать черновик как новое письмо или как ответ на открытое письмо в Gmail. Когда обработчик вызывает функцию обратного вызова для создания черновика, он передает ей объект события.
Подробнее о том, как создавать черновики писем… |
setOnClickOpenLinkAction |
Пользователь нажимает на виджет. |
CardActionImageImageButtonDecoratedTextTextButton
|
Задает Action, чтобы открывать URL, когда пользователь нажимает на виджет. Используйте этот обработчик, если вам нужно создать URL или выполнить другие действия до открытия ссылки. В противном случае обычно проще использовать setOpenLink.
URL можно открыть только в новом окне. Когда окно закрыто, вы можете перезагрузить дополнение в интерфейсе. |
setOpenLink |
Пользователь нажимает на виджет. |
CardActionImageImageButtonDecoratedTextTextButton
|
Открывает URL при нажатии на виджет. Используйте этот обработчик, если вам известен URL и нужно только открыть его. В противном случае используйте setOnClickOpenLinkAction.
URL можно открыть в новом окне или на оверлее. Если закрыть его, можно перезагрузить дополнение в интерфейсе. |
setSuggestionsAction |
Пользователь вводит текст в поле ввода. |
TextInput
|
Задает Action
, который выполняет функцию Apps Script, когда пользователь вводит текст в виджет ввода текста. Обработчик автоматически передает объект события вызываемой функции.
Подробнее о подсказках автозаполнения для текстовых полей… |
Функции обратного вызова
Функции обратного вызова выполняются, когда срабатывает Action. Поскольку функции обратного вызова являются функциями Apps Script, они могут выполнять почти все, что и другие функции скрипта.
Функция обратного вызова иногда возвращает определенный объект ответа. Эти типы ответов указывают на дополнительные операции, которые необходимо выполнить после завершения обратного вызова, например показать новую карточку или предложить подсказки автозаполнения. Если функция обратного вызова должна вернуть определенный объект ответа, используйте класс конструктора в сервисе карт, чтобы создать этот объект.
В таблице ниже указано, когда функции обратного вызова должны возвращать определенный объект ответа для определенных действий. Эти действия не зависят от конкретного размещаемого приложения, которое расширяет дополнение:
| Попытка действия | Функция обратного вызова должна возвращать |
|---|---|
| Навигация | ActionResponse |
Показать Notification |
ActionResponse |
Как открыть ссылку с помощью setOnClickOpenLinkAction |
ActionResponse |
| Показывать подсказки автозаполнения | SuggestionResponse |
| Используйте универсальное действие. | UniversalActionResponse |
| Другие действия | Nothing |
Действия для размещаемых приложений Google Workspace
Кроме того, у каждого размещаемого приложения есть собственный набор действий, которые можно выполнять только в нем. Подробные сведения приведены в следующих руководствах:
При использовании классов конструктора ответов вызовите метод build, чтобы создать объекты ответов. В противном случае возникнет ошибка.
Универсальные действия определяются в манифесте проекта и не требуют объектов Action, но их функции обратного вызова должны возвращать UniversalActionResponse.
Объекты событий действий
Когда дополнение запускает Action, интерфейс автоматически создает объект события JSON и передает его в качестве аргумента функции обратного вызова Action. Этот объект события содержит информацию о текущем клиентском контексте, например текущие значения всех интерактивных виджетов на отображаемой карточке.
Объекты событий действий имеют определенную структуру JSON, которая позволяет упорядочивать содержащуюся в них информацию. Та же структура используется, когда триггер главной страницы срабатывает для создания главной страницы или когда контекстный триггер срабатывает для обновления экрана дополнения.
Полное описание структуры объекта события приведено в разделе Объекты событий.
Дополнения Gmail использовали упрощенную версию структуры объекта события, которая теперь устарела. Для обеспечения обратной совместимости все поля исходного объекта события дополнений Gmail по-прежнему содержатся в новой структуре объекта события (см. структуру объекта события).
Однако та же информация воспроизводится в подструктурах объекта commonEventObject
и события Gmail. Если вы преобразуете дополнение Gmail в дополнение Google Workspace, измените код, чтобы использовать обновленные поля объекта события. В конечном итоге поля исходного объекта мероприятия Gmail будут удалены.