Создайте интерактивную карточку или диалог.

На этой странице объясняется, как добавлять виджеты и элементы пользовательского интерфейса к карточкам или диалоговым сообщениям, чтобы пользователи могли взаимодействовать с вашим приложением Google Chat, например, нажимая кнопку или отправляя информацию.

Используйте конструктор карточек для разработки и предварительного просмотра карточных сообщений JSON для приложений чата:

Откройте конструктор карточек

Предварительные условия

Приложение Google Chat с интерактивными функциями. Чтобы создать интерактивное приложение чата, выполните одно из следующих кратких руководств в зависимости от архитектуры приложения , которую вы хотите использовать:

Добавить кнопку

Виджет ButtonList отображает набор кнопок. Кнопки могут отображать текст, значок или и текст, и значок. Каждая Button поддерживает действие OnClick , которое происходит, когда пользователи нажимают кнопку. Например:

  • Откройте гиперссылку с помощью OpenLink , чтобы предоставить пользователям дополнительную информацию.
  • Запустите action , которое запускает пользовательскую функцию, например вызов API.

Для удобства кнопки поддерживают альтернативный текст.

Добавьте кнопку, которая запускает пользовательскую функцию

Ниже представлена ​​карточка, состоящая из виджета ButtonList с двумя кнопками. Одна кнопка открывает документацию для разработчиков Google Chat на новой вкладке. Другая кнопка запускает пользовательскую функцию goToView() и передает параметр viewType="BIRD EYE VIEW" .

Добавьте кнопку произвольного цвета и деактивированную кнопку.

Вы можете запретить пользователям нажимать кнопку, установив "disabled": "true" .

Ниже показана карточка, состоящая из виджета ButtonList с двумя кнопками. Одна кнопка использует поле Color для настройки цвета фона кнопки. Другая кнопка деактивирована с помощью поля Disabled , что не позволяет пользователю нажать кнопку и выполнить функцию.

Добавляем кнопку со значком

Ниже показана карточка, состоящая из виджета ButtonList с двумя виджетами Button значками. Одна кнопка использует knownIcon для отображения встроенного значка электронной почты Google Chat. Другая кнопка использует поле iconUrl для отображения пользовательского виджета значка .

Добавьте кнопку со значком и текстом

Ниже показана карточка, состоящая из виджета ButtonList , который предлагает пользователю отправить электронное письмо. На первой кнопке отображается значок электронной почты, а на второй — текст. Пользователь может щелкнуть значок или текстовую кнопку, чтобы запустить функцию sendEmail .

Добавьте выбираемые элементы пользовательского интерфейса

Виджет 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 :

Скрипт приложений

apps-script/selection-input/on-widget-update.gs
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

Node.js

узел/выбор-вход/on-widget-update.js
/**
 * Widget update event handler.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  const actionName = event.common["invokedFunction"];
  if (actionName !== "getContacts") {
    return {};
  }

  return {
    actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: {
        suggestions: {
          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
            },
          ]
        }
      }
    }
  };
}

Добавьте поле, в которое пользователь может ввести текст

Виджет 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» .