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