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