Ajouter des éléments d'interface utilisateur interactifs aux fiches

Cette page explique comment ajouter des widgets et des éléments d'interface utilisateur aux cartes afin que les utilisateurs puissent interagir avec votre application Google Chat cliquer sur un bouton ou soumettre des informations.

Les applications Chat peuvent utiliser les interfaces Chat suivantes pour créer des fiches interactives:

  • Messages contenant une ou plusieurs fiches.
  • Pages d'accueil, Il s'agit d'une fiche qui apparaît dans l'onglet Accueil messages avec l'application Chat.
  • Les boîtes de dialogue, qui sont des fiches qui s'ouvrent dans une nouvelle fenêtre à partir des messages et des pages d'accueil.

Lorsque les utilisateurs interagissent avec des fiches, les applications Chat peuvent exploiter les données qu'ils reçoivent pour les traiter et y répondre en conséquence. Pour en savoir plus, consultez Collecter et traiter les informations des utilisateurs de Google Chat


Utilisez Card Builder pour concevoir et prévisualiser la messagerie et les interfaces utilisateur des applications Chat:

Ouvrir Card Builder

Prérequis

Une application Google Chat avec des fonctionnalités interactives. Pour créer un interactive, suivez l'un des guides de démarrage rapide suivants sur l'architecture de l'application que vous souhaitez utiliser:

Ajouter un bouton

La Widget ButtonList affiche un ensemble de boutons. Les boutons peuvent afficher du texte, un une icône, ou les deux texte et une icône. Chaque Button prend en charge un Action OnClick qui se produit lorsque les utilisateurs cliquent sur le bouton. Exemple :

  • Ouvrir un lien hypertexte avec OpenLink afin de fournir des informations supplémentaires aux utilisateurs.
  • Lancez une action qui exécute une fonction personnalisée, comme appeler une API.

Pour des raisons d'accessibilité, les boutons acceptent un texte alternatif.

Ajouter un bouton qui exécute une fonction personnalisée

Voici une fiche composée d'un widget ButtonList avec deux boutons. Un bouton permet d'ouvrir la documentation Google Chat pour les développeurs dans un nouvel onglet. La L'autre bouton exécute une fonction personnalisée appelée goToView() et transmet la Paramètre viewType="BIRD EYE VIEW".

Ajouter un bouton avec le style Material Design

Vous trouverez ci-dessous un ensemble de boutons dans différents boutons Material Design. .

Pour appliquer le style Material Design, n'incluez pas la "couleur" .

Ajoutez un bouton avec une couleur personnalisée et un bouton désactivé

Vous pouvez empêcher les utilisateurs de cliquer sur un bouton en définissant "disabled": "true".

Vous trouverez ci-dessous une fiche composée d'un widget ButtonList avec deux . L'un des boutons utilise Champ Color pour personnaliser l'arrière-plan du bouton couleur. L'autre bouton est désactivé avec le champ Disabled, qui empêche l'utilisateur de cliquer sur le bouton et d'exécuter la fonction.

Ajouter un bouton avec une icône

Vous trouverez ci-dessous une fiche composée d'un widget ButtonList avec deux icônes. Widgets Button. L'un des boutons utilise knownIcon pour afficher l'icône d'e-mail intégrée à Google Chat. L'autre bouton utilise le champ iconUrl pour afficher un widget d'icône personnalisée.

Ajouter un bouton avec une icône et du texte

Vous trouverez ci-dessous une fiche composée d'un widget ButtonList qui invite à l'utilisateur d'envoyer un e-mail. Le premier bouton affiche une icône d'e-mail et le deuxième bouton affiche du texte. L'utilisateur peut cliquer sur l'icône ou le texte pour exécuter la fonction sendEmail.

Personnaliser le bouton pour une section réductible

Personnalisez le bouton de commande permettant de réduire et de développer les sections d'une . Choisissez parmi une gamme d'icônes ou d'images pour représenter visuellement le contenu de la section, ce qui permet aux utilisateurs de mieux comprendre les informations.

Ajouter un menu à développer

La Overflow menu peuvent être utilisées dans les fiches Chat pour proposer des options et actions supplémentaires. Elle permet vous incluez plus d'options sans encombrer l'interface de la carte, garantissant ainsi une conception propre et organisée.

Ajouter une liste de chips

ChipList widget permet d'afficher des informations de manière polyvalente et visuellement attrayante. Utilisez des listes de chips pour représenter des tags, des catégories ou d'autres données pertinentes. plus facile pour les utilisateurs de naviguer dans votre contenu et d'interagir avec celui-ci.

Recueillir des informations auprès des utilisateurs

Cette section explique comment ajouter des widgets qui collectent des informations, comme du texte ou des sélections.

Pour savoir comment traiter les données saisies par les utilisateurs, consultez Collecter et traiter les informations des utilisateurs de Google Chat

Collecter du texte

Le widget TextInput fournit un champ dans lequel les utilisateurs peuvent saisir du texte. La le widget prend en charge les suggestions, qui aident les utilisateurs à saisir des données uniformes, et lors des modifications actions, qui sont Actions qui s'exécutent lorsqu'une modification est apportée au champ de saisie de texte, par exemple lorsqu'un utilisateur ajoute ou supprimer du texte.

Lorsque vous devez collecter des données abstraites ou inconnues auprès des utilisateurs, utilisez ce Widget TextInput. Pour collecter des données définies auprès des utilisateurs, utilisez le SelectionInput .

Voici une fiche composée d'un widget TextInput:

Collecter les dates ou les heures

La Widget DateTimePicker permet aux utilisateurs de saisir une date, une heure ou les deux à la fois. Les utilisateurs peuvent également utiliser le sélecteur pour sélectionner des dates et des heures. Si les utilisateurs saisissent une date ou une heure non valide, le sélecteur affiche une erreur qui invite les utilisateurs à saisir les informations correctement.

Vous trouverez ci-dessous une fiche comportant trois types différents Widgets DateTimePicker:

Autoriser les utilisateurs à sélectionner des éléments

Le widget SelectionInput propose un ensemble d'éléments sélectionnables, tels que des cases à cocher, des cases d'option, des commutateurs ou un menu déroulant. Vous pouvez utiliser ce widget pour collecter des données définies et standardisées auprès des utilisateurs. Pour collecter des données non définies des utilisateurs, utilisez plutôt le widget TextInput.

Le widget SelectionInput prend en charge les suggestions, qui aident les utilisateurs à saisir des variables uniformes les données et les actions lors d'une modification, qui sont Actions qui s'exécutent lorsqu'une modification se produit dans un champ de saisie de sélection, comme dans le cas d'un en sélectionnant ou en désélectionnant un élément.

Les applications de chat peuvent recevoir et traiter la valeur des éléments sélectionnés. Pour en savoir plus sur l'utilisation des entrées de formulaire, consultez Traiter les informations saisies par les utilisateurs.

Cette section fournit des exemples de cartes qui utilisent le widget SelectionInput. Les exemples utilisent différents types d'entrées de section:

Ajouter une case à cocher

Vous trouverez ci-dessous une fiche demandant à l'utilisateur d'indiquer si un contact est professionnel, personnel ou les deux, à l'aide d'un widget SelectionInput qui utilise des cases à cocher:

Ajouter une case d'option

Vous trouverez ci-dessous une fiche demandant à l'utilisateur d'indiquer si un contact est professionnel ou personnel avec un widget SelectionInput qui utilise cases d'option:

Ajouter un bouton bascule

Vous trouverez ci-dessous une fiche demandant à l'utilisateur d'indiquer si un contact est professionnel, personnel ou les deux grâce à un widget SelectionInput qui utilise des contacteurs:

Vous trouverez ci-dessous une fiche demandant à l'utilisateur d'indiquer si un contact est professionnel ou personnel avec un widget SelectionInput qui utilise un menu déroulant:

Ajouter un menu multi-sélection

La fiche ci-dessous invite l'utilisateur à sélectionner des contacts. dans un menu multi-sélection:

Vous pouvez insérer des éléments pour un menu multi-sélection à partir des données suivantes sources dans Google Workspace:

  • Utilisateurs de Google Workspace: vous ne pouvez renseigner que les utilisateurs du domaine même organisation Google Workspace.
  • Espaces Chat: utilisateur saisissant des éléments dans la sélection multiple peuvent uniquement afficher et sélectionner les espaces auxquels ils appartiennent dans leur organisation Google Workspace.

Pour utiliser les sources de données Google Workspace, vous devez spécifier le platformDataSource . Contrairement aux autres types d'entrée de sélection, vous omettez SectionItem car ces éléments de sélection sont extraits de manière dynamique Google Workspace.

Le code suivant montre un menu multi-sélection d'utilisateurs Google Workspace. Pour renseigner les utilisateurs, l'entrée de sélection définit commonDataSource sur USER:

JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

Le code suivant montre un menu multi-sélection de Chat des espaces. Pour remplir les espaces, la sélection spécifie la hostAppDataSource. Le menu multi-sélection définit également defaultToCurrentSpace sur true, ce qui fait de l'espace actuel l'espace par défaut sélection dans le menu:

JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

Les menus à sélection multiple peuvent également remplir des éléments à partir de données tierces ou externes source. Par exemple, vous pouvez utiliser des menus à sélection multiple pour aider l'utilisateur à effectuer une sélection Liste des prospects commerciaux à partir d'un système de gestion de la relation client (CRM)

Pour utiliser une source de données externe, vous devez utiliser le champ externalDataSource pour : Spécifiez une fonction qui renvoie des éléments à partir de la source de données.

Pour limiter le nombre de requêtes adressées à une source de données externe, vous pouvez inclure Suggestions d'éléments qui s'affichent dans le menu multi-sélection avant que les utilisateurs ne saisissent le menu. Vous pouvez, par exemple, insérer les contacts recherchés récemment pour le utilisateur. Pour insérer les éléments suggérés à partir d'une source de données externe, spécifiez SelectionItem d'objets.

Le code suivant montre un menu multi-sélection d'éléments d'une l'ensemble externe de contacts de l'utilisateur. Le menu affiche un contact par défaut et exécute la fonction getContacts pour récupérer et remplir les éléments source de données externe:

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
      }
    ]
  }
}

Pour les sources de données externes, vous pouvez aussi utiliser la saisie semi-automatique pour les éléments que les utilisateurs lancent dans le menu multi-sélection. Par exemple, si un utilisateur commence à saisir Atl pour une qui affiche les villes des États-Unis, votre L'application de chat peut suggérer automatiquement Atlanta avant l'utilisateur termine la saisie. Vous pouvez saisir semi-automatiquement jusqu'à 100 éléments.

Pour saisir semi-automatiquement des éléments, vous créez une fonction qui interroge les données externes source et renvoie des éléments chaque fois qu'un utilisateur effectue une saisie dans le menu multi-sélection. La doit effectuer les opérations suivantes:

  • Transmettez un objet d'événement qui représente l'interaction de l'utilisateur avec le menu.
  • Identifiez que l'événement d'interaction invokedFunction valeur correspond à la fonction du champ externalDataSource.
  • Lorsque les fonctions correspondent, renvoyer des éléments suggérés à partir des données externes source. Pour suggérer des éléments en fonction des types de données saisis par l'utilisateur, obtenez la valeur de l'attribut Clé autocomplete_widget_query. Cette valeur représente ce que l'utilisateur saisit dans le menu.

Le code suivant permet d'effectuer une saisie semi-automatique pour les éléments d'une ressource de données externe. Avec les l'exemple précédent, l'application Chat suggère des éléments en fonction Lorsque la fonction getContacts est déclenchée:

Apps Script

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

node/selection-input/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
            },
          ]
        }
      }
    }
  };
}

Valider les données saisies dans les fiches

Cette page explique comment valider les données saisies dans le action d'une carte et les widgets. Par exemple, vous pouvez vérifier qu'un champ de saisie de texte contient du texte saisi par la ou qu'elle contient un certain nombre de caractères.

Définir les widgets requis pour les actions

Dans le cadre du action de la carte, ajouter les noms des widgets dont une action a besoin à sa liste requiredWidgets.

Si l'un des widgets listés ici n'a pas de valeur lorsque cette action est appelée, l'envoi de l'action du formulaire est annulé.

Lorsque "all_widgets_are_required": "true" est défini pour une action, tous les widgets dans la fiche sont requis pour cette action.

Définir une action all_widgets_are_required en mode multi-sélection

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
              }
            ]
          }
        }
      ]
    }
  ]
}
Définir une action all_widgets_are_required dans 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"
          }
        }
      ]
    }
  ]
}
Définissez une action all_widgets_are_required dans le menu déroulant

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
              }
            ]
          }
        }
      ]
    }
  ]
}

Définir la validation d'un widget de saisie de texte

Dans la textInput de validation du widget, il peut spécifier le nombre maximal de caractères et le type d'entrée pour ce widget de saisie de texte.

Définir une limite de caractères pour un widget de saisie de texte

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
            }
          }
        }
      ]
    }
  ]
}
Définir le type d'entrée pour un widget de saisie de texte

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"
            }
          }
        }
      ]
    }
  ]
}

Résoudre les problèmes

Lorsqu'une application ou card renvoie une erreur, la L'interface Chat affiche le message "Une erreur s'est produite". ou "Impossible de traiter votre demande." Parfois, l'interface utilisateur de Chat n'affiche aucun message d'erreur, mais que l'application ou la carte produit un résultat inattendu. Par exemple, un message de fiche peut ne pas s'affichent.

Même s'il est possible qu'aucun message d'erreur ne s'affiche dans l'interface utilisateur de Chat, Des messages d'erreur descriptifs et des données de journaux sont disponibles pour vous aider à corriger les erreurs. Lorsque la journalisation des erreurs est activée pour les applications Chat. Pour obtenir de l'aide, le débogage et la correction des erreurs, consultez Résoudre les problèmes liés à Google Chat