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