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