Дополнительные действия обеспечивают интерактивное поведение виджетов . Создав действие, вы определяете, что происходит, когда пользователь выбирает или обновляет виджет.
В большинстве случаев вы можете определить дополнительные действия, используя объекты Action , предоставляемые сервисом Google Apps Script Card . Каждое Action связывается с функцией обратного вызова при его создании. Вы реализуете функцию обратного вызова для выполнения выбранных шагов при взаимодействии пользователя с виджетом. Вы также должны связать Action с виджетом, используя соответствующую функцию обработчика виджета , которая определяет, какой тип взаимодействия запускает функцию обратного вызова Action .
Настройте виджет с помощью Action , используя следующий процесс:
- Создайте объект
Action, указав функцию обратного вызова, которую он должен выполнить, а также все необходимые параметры. - Вызовите соответствующую функцию обработчика виджета , используя объект
Action. - Реализуйте функцию обратного вызова для выполнения требуемого действия.
Не следует путать объекты Action с объектами CardAction . Объекты CardAction — это пункты меню в виде заголовков карточек, тогда как объекты Action определяют реакции на взаимодействие пользователя с пользовательским интерфейсом.
Widget handler functions
Для привязки виджета к Action или другому поведению используйте функцию обработчика виджета. Функция обработчика определяет, какой тип взаимодействия (например, щелчок по виджету или редактирование текстового поля) запускает действие. Функция обработчика также определяет, какие шаги, если таковые имеются, предпринимает пользовательский интерфейс после завершения действия.
В таблице ниже перечислены различные типы обработчиков для виджетов и виджеты, с которыми они используются:
| Handler function | Запускает действие | Применимые виджеты | Описание |
|---|---|---|---|
setOnChangeAction | The widget value changes | DatePickerDateTimePickerSelectionInputSwitchTextInput TimePicker | Задает Action , которое выполняет функцию Apps Script, когда виджет теряет фокус, например, когда пользователь вводит текст в поле ввода и нажимает Enter. Обработчик автоматически передает объект события вызываемой функции. При выборе этого параметра в объект события можно добавить дополнительную информацию о параметрах. |
setOnClickAction | The user clicks the widget | CardActionImageImageButtonDecoratedTextTextButton | Sets an Action that executes an Apps Script function when the user clicks the widget. The handler automatically passes an event object to the function it calls. You can insert optional parameter information in this event object. |
setComposeAction | The user clicks the widget | CardActionImageImageButtonDecoratedTextTextButton | Gmail specific. Sets an Action that builds an email draft, then presents that draft to the user in a Gmail UI compose window. You can build the draft as a new message or a reply to the open message in Gmail. When the handler calls the draft-building callback function, it passes an event object to the callback function. See Compose draft messages for more details. |
setOnClickOpenLinkAction | The user clicks the widget | CardActionImageImageButtonDecoratedTextTextButton | Задает Action , которое откроет URL-адрес при щелчке пользователя по виджету. Используйте этот обработчик, если необходимо сформировать URL-адрес или выполнить другие действия до открытия ссылки; в противном случае обычно проще использовать setOpenLink . Вы можете открыть URL-адрес только в новом окне. При закрытии вы можете вызвать перезагрузку пользовательского интерфейса дополнения. |
setOpenLink | The user clicks the widget | CardActionImageImageButtonDecoratedTextTextButton | Directly opens a URL when the user clicks the widget. Use this handler when you know the URL and only need to open it; otherwise use setOnClickOpenLinkAction . You can open the URL in a new window or in an overlay. When closed, you can cause the UI to reload the add-on. |
setSuggestionsAction | Пользователь вводит текст в поле ввода. | TextInput | Задает Action , которое выполняет функцию Apps Script, когда пользователь вводит текст в текстовое поле ввода. Обработчик автоматически передает объект события вызываемой функции. Дополнительные сведения см. в разделе «Подсказки автозаполнения для текстовых полей ввода» . |
Callback functions
Функции обратного вызова выполняются при срабатывании Action . Поскольку функции обратного вызова являются функциями Apps Script, вы можете назначить им практически любые функции скрипта.
Функция обратного вызова иногда возвращает конкретный объект ответа. Такие ответы указывают на дополнительные операции, которые должны произойти после завершения выполнения функции обратного вызова, например, отображение новой карточки или предоставление подсказок автозаполнения. Когда функция обратного вызова должна возвращать конкретный объект ответа, вы используете класс-конструктор в службе Card для создания этого объекта.
В следующей таблице показано, когда ваши функции обратного вызова должны возвращать определенный объект ответа для определенных действий. Все эти действия не зависят от конкретного хост-приложения, на которое распространяется действие дополнения:
| Action attempted | Функция обратного вызова должна возвращать |
|---|---|
| Навигация | ActionResponse |
Отобразить Notification | ActionResponse |
Open a link using setOnClickOpenLinkAction | ActionResponse |
| Отображать подсказки автозаполнения | SuggestionResponse |
| Используйте универсальное действие | UniversalActionResponse |
| Другие действия | Ничего |
Действия для приложений, размещенных в Google Workspace.
Помимо перечисленных действий, каждое хост-приложение имеет свой собственный набор действий, которые могут быть выполнены только на этом хосте. Подробности см. в следующих руководствах:
При использовании классов построения ответов вызовите метод build для создания объектов ответов. В противном случае возникнет ошибка.
Универсальные действия определяются в манифесте проекта и не требуют объектов Action , но их функции обратного вызова должны возвращать объект UniversalActionResponse .
Action event objects
Когда ваше дополнение запускает Action , пользовательский интерфейс автоматически формирует объект события JSON и передает его в качестве аргумента функции обратного вызова Action . Этот объект события содержит информацию о текущем контексте пользователя на стороне клиента, например, о текущих значениях всех интерактивных виджетов в отображаемой карточке.
Объекты событий действий имеют определенную структуру JSON, которая организует содержащуюся в них информацию. Та же структура используется, когда срабатывает триггер главной страницы для ее создания или когда срабатывает контекстный триггер для обновления отображения дополнения.
Полное описание структуры объекта события см. в разделе «Объекты событий».
В дополнениях Gmail использовалась упрощенная версия этой структуры объекта события, которая теперь устарела. Для обеспечения обратной совместимости все поля исходного объекта события дополнений Gmail по-прежнему содержатся в новой структуре объекта события (см. структуру объекта события ). Однако та же информация воспроизводится в подструктурах commonEventObject и объекта события Gmail . Если вы обновляете дополнение Gmail до дополнения Google Workspace, измените свой код, чтобы использовать обновленные поля объекта события. В конечном итоге исходные поля объекта события Gmail будут удалены.