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

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


Создавайте и просматривайте карты с помощью Card Builder.

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

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

  • Аккаунт Google Workspace с доступом к Google Chat .
  • Опубликованное приложение чата. Чтобы создать приложение 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 :

    Устранение неполадок

    Когда приложение или карточка Google Chat возвращает ошибку, в интерфейсе Chat отображается сообщение «Что-то пошло не так». или «Невозможно обработать ваш запрос». Иногда в пользовательском интерфейсе чата не отображается сообщение об ошибке, но приложение или карточка чата выдает неожиданный результат; например, сообщение с карточкой может не появиться.

    Хотя сообщение об ошибке может не отображаться в пользовательском интерфейсе чата, доступны описательные сообщения об ошибках и данные журнала, которые помогут вам исправить ошибки, если включено ведение журнала ошибок для приложений чата. Информацию о просмотре, отладке и исправлении ошибок см. в разделе «Устранение неполадок и исправление ошибок Google Chat» .