На этой странице объясняется, как добавлять виджеты и элементы пользовательского интерфейса к карточкам или диалоговым сообщениям, чтобы пользователи могли взаимодействовать с вашим приложением Google Chat, например, нажимая кнопку или отправляя информацию.
Используйте конструктор карточек для разработки и предварительного просмотра карточных сообщений JSON для приложений чата:
Откройте конструктор карточекПредварительные условия
Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата, выполните одно из следующих кратких руководств в зависимости от архитектуры приложения , которую вы хотите использовать:
- HTTP-сервис с облачными функциями Google
- Скрипт Google Apps
- Google Cloud Dialogflow CX
- Google Cloud Pub/Sub
Добавить кнопку
Виджет ButtonList
отображает набор кнопок. Кнопки могут отображать текст, значок или и текст, и значок. Каждая Button
поддерживает действие OnClick
, которое происходит, когда пользователи нажимают кнопку. Например:
- Откройте гиперссылку с помощью
OpenLink
, чтобы предоставить пользователям дополнительную информацию. - Запустите
action
, которое запускает пользовательскую функцию, например вызов API.
Для удобства кнопки поддерживают альтернативный текст.
Добавьте кнопку, которая запускает пользовательскую функцию
Ниже представлена карточка, состоящая из виджета ButtonList
с двумя кнопками. Одна кнопка открывает документацию для разработчиков Google Chat на новой вкладке. Другая кнопка запускает пользовательскую функцию goToView()
и передает параметр viewType="BIRD EYE VIEW"
.
Добавьте кнопку в стиле Material Design.
Ниже показан набор кнопок в различных стилях кнопок Material Design.
Чтобы применить стиль Material Design, не включайте атрибут «цвет».
Добавьте кнопку произвольного цвета и деактивированную кнопку.
Вы можете запретить пользователям нажимать кнопку, установив "disabled": "true"
.
Ниже показана карточка, состоящая из виджета ButtonList
с двумя кнопками. Одна кнопка использует поле Color
для настройки цвета фона кнопки. Другая кнопка деактивирована с помощью поля Disabled
, что не позволяет пользователю нажать кнопку и выполнить функцию.
Добавляем кнопку со значком
Ниже показана карточка, состоящая из виджета ButtonList
с двумя виджетами Button
значками. Одна кнопка использует knownIcon
для отображения встроенного значка электронной почты Google Chat. Другая кнопка использует поле iconUrl
для отображения пользовательского виджета значка .
Добавьте кнопку со значком и текстом
Ниже показана карточка, состоящая из виджета ButtonList
, который предлагает пользователю отправить электронное письмо. На первой кнопке отображается значок электронной почты, а на второй — текст. Пользователь может щелкнуть значок или текстовую кнопку, чтобы запустить функцию sendEmail
.
Добавить меню переполнения
Overflow menu
можно использовать в карточках чата, чтобы предлагать дополнительные параметры и действия. Это позволяет вам включать больше опций, не загромождая интерфейс карты, обеспечивая чистый и организованный дизайн.
Добавить список фишек
Виджет ChipList
обеспечивает универсальный и визуально привлекательный способ отображения информации. Используйте списки чипов для представления тегов, категорий или других соответствующих данных, что упрощает пользователям навигацию и взаимодействие с вашим контентом.
Добавьте выбираемые элементы пользовательского интерфейса
Виджет SelectionInput
предоставляет набор выбираемых элементов, таких как флажки, переключатели, переключатели или раскрывающееся меню. Вы можете использовать этот виджет для сбора определенных и стандартизированных данных от пользователей. Чтобы собирать неопределенные данные от пользователей, используйте вместо этого виджет TextInput
.
Виджет SelectionInput
поддерживает предложения, которые помогают пользователям вводить унифицированные данные, и действия при изменении, которые представляют собой Actions
, которые выполняются, когда происходит изменение в поле ввода выбора, например, когда пользователь выбирает или отменяет выбор элемента.
Приложения чата могут получать и обрабатывать значения выбранных элементов. Подробные сведения о работе с входными данными формы см. в разделе Обработка информации, введенной пользователями .
В этом разделе приведены примеры карточек, использующих виджет SelectionInput
. В примерах используются разные типы входных данных раздела:
Добавить флажок
Ниже показано диалоговое окно, в котором пользователю предлагается указать, является ли контакт профессиональным, личным или и тем, и другим, с помощью виджета SelectionInput
, в котором используются флажки:
Добавить переключатель
Ниже показано диалоговое окно, в котором пользователю предлагается указать, является ли контакт профессиональным или личным, с помощью виджета SelectionInput
, в котором используются переключатели:
Добавить переключатель
Ниже показано диалоговое окно, в котором пользователю предлагается указать, является ли контакт профессиональным, личным или и тем, и другим, с помощью виджета SelectionInput
, использующего переключатели:
Добавить раскрывающееся меню
Ниже показано диалоговое окно, в котором пользователю предлагается указать, является ли контакт профессиональным или личным, с помощью виджета SelectionInput
, использующего раскрывающееся меню:
Добавить меню с множественным выбором
Ниже показано диалоговое окно, в котором пользователю предлагается выбрать контакты из меню с множественным выбором:
Используйте источники данных для меню с множественным выбором
В следующем разделе объясняется, как использовать меню с множественным выбором для заполнения данных из динамических источников, таких как приложение Google Workspace или внешний источник данных.
Источники данных из Google Workspace
Вы можете заполнить элементы для меню с множественным выбором из следующих источников данных в Google Workspace:
- Пользователи Google Workspace . Вы можете добавлять пользователей только в пределах одной организации Google Workspace.
- Пространства чата . Пользователь, вводящий элементы в меню с множественным выбором, может просматривать и выбирать только пространства, к которым они принадлежат, в своей организации Google Workspace.
Чтобы использовать источники данных Google Workspace, вы указываете поле platformDataSource
. В отличие от других типов входных данных выбора, вы опускаете объекты SectionItem
, поскольку эти элементы выбора динамически получаются из Google Workspace.
Следующий код показывает меню с множественным выбором пользователей Google Workspace. Чтобы заполнить пользователей, вход выбора устанавливает commonDataSource
в USER
:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"commonDataSource": "USER"
}
}
}
Следующий код показывает меню с множественным выбором пространств чата. Для заполнения пробелов входные данные выбора указывают поле hostAppDataSource
. Меню множественного выбора также устанавливает для defaultToCurrentSpace
значение true
, что делает текущее пространство выбором по умолчанию в меню:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Источники данных за пределами Google Workspace
В меню с множественным выбором также можно заполнять элементы из стороннего или внешнего источника данных. Например, вы можете использовать меню с множественным выбором, чтобы помочь пользователю выбрать из списка потенциальных клиентов из системы управления взаимоотношениями с клиентами (CRM).
Чтобы использовать внешний источник данных, вы используете поле externalDataSource
, чтобы указать функцию, которая возвращает элементы из источника данных.
Чтобы уменьшить количество запросов к внешнему источнику данных, вы можете включить предлагаемые элементы, которые появляются в меню с множественным выбором до того, как пользователи введут его в меню. Например, вы можете заполнить для пользователя недавно найденные контакты. Чтобы заполнить предлагаемые элементы из внешнего источника данных, укажите объекты SelectionItem
.
Следующий код показывает меню с множественным выбором элементов из внешнего набора контактов пользователя. По умолчанию в меню отображается один контакт и запускается функция getContacts
для получения и заполнения элементов из внешнего источника данных:
JSON
{
"selectionInput": {
"name": "contacts",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 5,
"multiSelectMinQueryLength": 2,
"externalDataSource": {
"function": "getContacts"
},
"items": [
{
"text": "Contact 3",
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"bottomText": "Contact three description",
"selected": false
}
]
}
}
Для внешних источников данных вы также можете автозаполнять элементы, которые пользователи начинают вводить в меню с множественным выбором. Например, если пользователь начинает вводить Atl
для меню, в котором представлены города в США, ваше приложение Chat может автоматически предложить Atlanta
до того, как пользователь завершит ввод. Вы можете автозаполнить до 100 элементов.
Для автозаполнения элементов вы создаете функцию, которая запрашивает внешний источник данных и возвращает элементы всякий раз, когда пользователь вводит данные в меню с множественным выбором. Функция должна делать следующее:
- Передайте объект события, который представляет взаимодействие пользователя с меню.
- Определите, что значение
invokedFunction
события взаимодействия соответствует функции из поляexternalDataSource
. - Если функции совпадают, возвращайте предлагаемые элементы из внешнего источника данных. Чтобы предлагать элементы на основе того, что вводит пользователь, получите значение ключа
autocomplete_widget_query
. Это значение представляет то, что пользователь вводит в меню.
Следующий код автоматически заполняет элементы из внешнего ресурса данных. Используя предыдущий пример, приложение Chat предлагает элементы в зависимости от того, когда срабатывает функция getContacts
:
Скрипт приложений
Node.js
Добавьте поле, в которое пользователь может ввести текст
Виджет TextInput
предоставляет поле, в котором пользователи могут вводить текст. Виджет поддерживает предложения, которые помогают пользователям вводить унифицированные данные, и действия при изменении, которые представляют собой Actions
, которые выполняются при изменении в поле ввода текста, например, когда пользователь добавляет или удаляет текст.
Если вам нужно собрать абстрактные или неизвестные данные от пользователей, используйте этот виджет TextInput
. Чтобы собрать определенные данные от пользователей, используйте вместо этого виджет SelectionInput
.
Чтобы обработать текст, вводимый пользователями, см. раздел Обработка информации, введенной пользователями .
Ниже представлена карточка, состоящая из виджета TextInput
:
Разрешить пользователю выбирать дату и время
Виджет DateTimePicker
позволяет пользователям вводить дату, время или дату и время одновременно. Или пользователи могут использовать средство выбора для выбора даты и времени. Если пользователи вводят неверную дату или время, средство выбора отображает ошибку, которая предлагает пользователям ввести информацию правильно.
Чтобы обработать значения даты и времени, вводимые пользователями, см. раздел Обработка информации, введенной пользователями .
Ниже показана карточка, состоящая из трех разных типов виджетов DateTimePicker
:
Проверка данных, введенных в карты
На этой странице объясняется, как проверить данные, введенные в action
карты и виджеты. Например, вы можете проверить, что поле ввода текста содержит текст, введенный пользователем, или что оно содержит определенное количество символов.
Установите необходимые виджеты для действий
В рамках action
карточки добавьте названия виджетов, которые нужны действию, в список requiredWidgets
.
Если какие-либо виджеты, перечисленные здесь, не имеют значения при вызове этого действия, то отправка действия формы отменяется.
Если для действия установлено "all_widgets_are_required": "true"
, то для этого действия требуются все виджеты на карточке.
Установите действие all_widgets_are_required
в множественном выборе
JSON
{
"sections": [
{
"header": "Select contacts",
"widgets": [
{
"selectionInput": {
"type": "MULTI_SELECT",
"label": "Selected contacts",
"name": "contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"value": "contact-1",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 1",
"bottomText": "Contact one description",
"selected": false
},
{
"value": "contact-2",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 2",
"bottomText": "Contact two description",
"selected": false
},
{
"value": "contact-3",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 3",
"bottomText": "Contact three description",
"selected": false
},
{
"value": "contact-4",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 4",
"bottomText": "Contact four description",
"selected": false
},
{
"value": "contact-5",
"startIconUri": "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
"text": "Contact 5",
"bottomText": "Contact five description",
"selected": false
}
]
}
}
]
}
]
}
Установите действие all_widgets_are_required
в dateTimePicker.
JSON
{
"sections": [
{
"widgets": [
{
"textParagraph": {
"text": "A datetime picker widget with both date and time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_and_time",
"label": "meeting",
"type": "DATE_AND_TIME"
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just date:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_date_only",
"label": "Choose a date",
"type": "DATE_ONLY",
"onChangeAction":{
"all_widgets_are_required": true
}
}
},
{
"textParagraph": {
"text": "A datetime picker widget with just time:"
}
},
{
"divider": {}
},
{
"dateTimePicker": {
"name": "date_time_picker_time_only",
"label": "Select a time",
"type": "TIME_ONLY"
}
}
]
}
]
}
Установите действие all_widgets_are_required
в раскрывающемся меню.
JSON
{
"sections": [
{
"header": "Section Header",
"collapsible": true,
"uncollapsibleWidgetsCount": 1,
"widgets": [
{
"selectionInput": {
"name": "location",
"label": "Select Color",
"type": "DROPDOWN",
"onChangeAction": {
"all_widgets_are_required": true
},
"items": [
{
"text": "Red",
"value": "red",
"selected": false
},
{
"text": "Green",
"value": "green",
"selected": false
},
{
"text": "White",
"value": "white",
"selected": false
},
{
"text": "Blue",
"value": "blue",
"selected": false
},
{
"text": "Black",
"value": "black",
"selected": false
}
]
}
}
]
}
]
}
Установите проверку для виджета ввода текста
В поле проверки виджета textInput
можно указать ограничение на количество символов и тип ввода для этого виджета ввода текста.
Установите ограничение на количество символов для виджета ввода текста
JSON
{
"sections": [
{
"header": "Tell us about yourself",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "favoriteColor",
"label": "Favorite color",
"type": "SINGLE_LINE",
"validation": {"character_limit":15},
"onChangeAction":{
"all_widgets_are_required": true
}
}
}
]
}
]
}
Установите тип ввода для виджета ввода текста
JSON
{
"sections": [
{
"header": "Validate text inputs by input types",
"collapsible": true,
"uncollapsibleWidgetsCount": 2,
"widgets": [
{
"textInput": {
"name": "mailing_address",
"label": "Please enter a valid email address",
"type": "SINGLE_LINE",
"validation": {
"input_type": "EMAIL"
},
"onChangeAction": {
"all_widgets_are_required": true
}
}
},
{
"textInput": {
"name": "validate_integer",
"label": "Please enter a number",
"type": "SINGLE_LINE",
"validation": {
"input_type": "INTEGER"
}
}
},
{
"textInput": {
"name": "validate_float",
"label": "Please enter a number with a decimal",
"type": "SINGLE_LINE",
"validation": {
"input_type": "FLOAT"
}
}
}
]
}
]
}
Устранение неполадок
Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.
Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .