Дополнительные действия обеспечивают интерактивное поведение виджетов . Создав действие, вы определяете, что происходит, когда пользователь выбирает или обновляет виджет.
В большинстве случаев вы можете определять дополнительные действия, используя объекты Action , предоставляемые службой Apps Script Card . Каждое Action связывается с функцией обратного вызова при его создании. Вы реализуете функцию обратного вызова для выполнения выбранных шагов при взаимодействии пользователя с виджетом. Вы также должны связать Action с виджетом, используя соответствующую функцию обработчика виджета , которая определяет, какой тип взаимодействия запускает функцию обратного вызова Action .
Настройте виджет с помощью Action , используя следующий общий процесс:
- Создайте объект
Action, указав функцию обратного вызова, которую он должен выполнить, а также все необходимые параметры. - Вызовите соответствующую функцию обработчика виджета , используя объект
Action. - Реализуйте функцию обратного вызова для выполнения требуемого действия.
Функции обработчика виджетов
Для привязки виджета к определенному Action или другому поведению используется функция обработчика виджета. Функция обработчика определяет, какой тип взаимодействия (например, щелчок по виджету или редактирование текстового поля) запускает действие. Функция обработчика также определяет, какие шаги, если таковые имеются, предпринимает пользовательский интерфейс после завершения действия.
В таблице ниже перечислены различные типы обработчиков для виджетов и виджеты, с которыми они используются:
| Функция обработчика | Запускает действие | Применимые виджеты | Описание |
|---|---|---|---|
setOnChangeAction() | Значение виджета изменяется | DatePickerDateTimePickerSelectionInputSwitchTextInput TimePicker | Задает Action , которое выполняет функцию Apps Script, когда виджет теряет фокус, например, когда пользователь вводит текст в поле ввода и нажимает Enter. Обработчик автоматически передает объект события вызываемой функции. При выборе этого параметра в объект события можно добавить дополнительную информацию о параметрах. |
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, вы можете назначить им практически любые функции, которые могут выполнять любые другие функции скрипта.
Функция обратного вызова иногда возвращает конкретный объект ответа. Такие ответы указывают на дополнительные операции, которые должны произойти после завершения выполнения функции обратного вызова, например, отображение новой карточки или предоставление подсказок автозаполнения. Когда функция обратного вызова должна возвращать конкретный объект ответа, вы используете класс-конструктор в службе Card для создания этого объекта.
В следующей таблице показано, когда ваши функции обратного вызова должны возвращать определенный объект ответа для определенных действий. Все эти действия не зависят от конкретного хост-приложения, на которое распространяется действие дополнения:
| Предпринятые действия | Функция обратного вызова должна возвращать |
|---|---|
| Перемещение между карточками | ActionResponse |
Отобразить Notification | ActionResponse |
Откройте ссылку с помощью setOnClickOpenLinkAction() | ActionResponse |
| Отображать подсказки автозаполнения | SuggestionResponse |
| Используйте универсальное действие | UniversalActionResponse |
| Другие действия | Ничего |
Действия для приложений, размещенных в Google Workspace.
Помимо перечисленных действий, каждое хост-приложение имеет свой собственный набор действий, которые могут быть выполнены только на этом хосте. Подробности см. в следующих руководствах:
Объекты событий действий
Когда ваше дополнение запускает Action , пользовательский интерфейс автоматически формирует объект события JSON и передает его в качестве аргумента функции обратного вызова Action . Этот объект события содержит информацию о текущем контексте пользователя на стороне клиента, например, о текущих значениях всех интерактивных виджетов в отображаемой карточке.
Объекты событий действий имеют определенную структуру JSON, которая организует содержащуюся в них информацию. Та же структура используется, когда срабатывает триггер главной страницы для ее создания или когда срабатывает контекстный триггер для обновления отображения дополнения.
Полное описание структуры объекта события см. в разделе «Объекты событий».