Cette page explique comment ajouter des widgets et des éléments d'interface utilisateur aux fiches ou aux messages de boîte de dialogue afin que les utilisateurs puissent interagir avec votre application Google Chat, par exemple en cliquant sur un bouton ou en envoyant des informations.
Utilisez le générateur de cartes pour concevoir et prévisualiser des messages de cartes JSON pour les applications Chat:
Ouvrir Card BuilderConditions préalables
Ajouter un bouton
Le widget ButtonList affiche un ensemble de boutons. Les boutons peuvent afficher du texte, une
icône ou les deux à la fois. Chaque Button accepte une action OnClick qui se produit lorsque les utilisateurs cliquent sur le bouton. Exemple :
- Ouvrez un lien hypertexte avec
OpenLinkafin de fournir des informations supplémentaires aux utilisateurs. - Exécutez un
actionqui exécute une fonction personnalisée, par exemple en appelant 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. L'autre bouton exécute une fonction personnalisée appelée goToView() et transmet le paramètre viewType="BIRD EYE VIEW".
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 boutons. L'un des boutons utilise le champ Color pour personnaliser la couleur d'arrière-plan du bouton. L'autre bouton est désactivé avec le champ Disabled, ce 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 widgets d'icône Button. Un bouton utilise le champ 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 à envoyer un e-mail. Le premier bouton affiche une icône d'e-mail et le second affiche du texte. L'utilisateur peut cliquer sur l'icône ou le bouton de texte pour exécuter la fonction sendEmail.
Ajouter des éléments d'interface utilisateur sélectionnables
Le widget SelectionInput fournit un ensemble d'éléments sélectionnables tels que des cases à cocher, des cases d'option, des boutons bascules 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 auprès des utilisateurs, utilisez plutôt le widget TextInput.
Le widget SelectionInput accepte les suggestions, qui aident les utilisateurs à saisir des données uniformes, et les actions en cas de modification, qui sont des Actions exécutées lorsqu'une modification se produit dans un champ de saisie de sélection, par exemple lorsqu'un utilisateur sélectionne ou désélectionne 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 Recevoir des données de formulaire.
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
La boîte de dialogue suivante affiche une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel, personnel ou les deux, à l'aide d'un widget SelectionInput utilisant des cases à cocher:
Ajouter une case d'option
L'écran suivant affiche une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel ou personnel avec un widget SelectionInput qui utilise des cases d'option:
Ajouter un bouton bascule
La boîte de dialogue suivante affiche une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel, personnel ou les deux avec un widget SelectionInput utilisant des commutateurs:
Ajouter un menu déroulant
La boîte de dialogue suivante affiche une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel ou personnel à l'aide d'un widget SelectionInput utilisant un menu déroulant:
Ajouter un menu multi-sélection
La boîte de dialogue suivante affiche une boîte de dialogue invitant l'utilisateur à sélectionner des contacts dans un menu multi-sélection:
Utiliser des sources de données pour les menus à sélection multiple
La section suivante explique comment utiliser les menus à sélection multiple pour renseigner des données à partir de sources dynamiques, telles qu'une application Google Workspace ou une source de données externe.
Sources de données de Google Workspace
Vous pouvez renseigner des éléments pour un menu multi-sélection à partir des sources de données suivantes dans Google Workspace:
- Utilisateurs Google Workspace: vous ne pouvez renseigner que des utilisateurs appartenant à la même organisation Google Workspace.
- Espaces Chat: l'utilisateur qui saisit des éléments dans le menu multi-sélection ne peut afficher et sélectionner que les espaces auxquels il appartient dans son organisation Google Workspace.
Pour utiliser les sources de données Google Workspace, spécifiez le champ platformDataSource. Contrairement aux autres types d'entrées de sélection, vous omettez les objets SectionItem, car ces éléments de sélection proviennent de Google Workspace de manière dynamique.
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 d'espaces Chat. Pour renseigner les espaces, la sélection spécifie le champ hostAppDataSource. Le menu multi-sélection définit également defaultToCurrentSpace sur true, ce qui fait de l'espace actuel la sélection par défaut dans le menu:
JSON
{
"selectionInput": {
"name": "spaces",
"type": "MULTI_SELECT",
"label": "Selected contacts",
"multiSelectMaxSelectedItems": 3,
"multiSelectMinQueryLength": 1,
"platformDataSource": {
"hostAppDataSource": {
"chatDataSource": {
"spaceDataSource": {
"defaultToCurrentSpace": true
}
}
}
}
}
}
Sources de données extérieures à Google Workspace
Les menus à sélection multiple peuvent également remplir des éléments à partir d'une source de données tierce ou externe. Par exemple, vous pouvez utiliser des menus à sélection multiple pour aider un utilisateur à effectuer une sélection dans une liste de prospects commerciaux à partir d'un système de gestion de la relation client (CRM).
Pour utiliser une source de données externe, vous devez spécifier une fonction qui renvoie des éléments à partir de la source de données à l'aide du champ externalDataSource.
Pour réduire le nombre de requêtes adressées à une source de données externe, vous pouvez inclure des suggestions d'éléments qui apparaissent dans le menu multi-sélection avant que les utilisateurs n'y saisissent. Par exemple, vous pouvez insérer les contacts récemment recherchés pour l'utilisateur. Pour insérer les éléments suggérés à partir d'une source de données externe, spécifiez des objets SelectionItem.
Le code suivant montre à l'utilisateur un menu multi-sélection d'éléments provenant d'un ensemble externe de contacts. Le menu affiche un contact par défaut et exécute la fonction getContacts pour récupérer et insérer des éléments à partir de la 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 également utiliser la saisie semi-automatique pour les éléments que les utilisateurs commencent à saisir dans le menu multi-sélection. Par exemple, si un utilisateur commence à saisir Atl pour un menu qui affiche des villes des États-Unis, votre application Chat peut suggérer automatiquement Atlanta avant la fin de la saisie. Vous pouvez saisir semi-automatiquement jusqu'à 100 éléments.
Pour utiliser la saisie semi-automatique des éléments, vous créez une fonction qui interroge la source de données externe et renvoie des éléments chaque fois qu'un utilisateur effectue une saisie dans le menu multi-sélection. La fonction doit effectuer les opérations suivantes:
- Transmettez un objet d'événement qui représente l'interaction de l'utilisateur avec le menu.
- Vérifiez que la valeur
invokedFunctionde l'événement d'interaction correspond à la fonction du champexternalDataSource. - Lorsque les fonctions correspondent, renvoyez des éléments suggérés à partir de la source de données externe. Pour suggérer des éléments en fonction de ce que l'utilisateur saisit, obtenez la valeur de la 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. À l'aide de l'exemple précédent, l'application Chat suggère des éléments en fonction du moment où la fonction getContacts est déclenchée:
Apps Script ;
Node.js
Ajouter un champ dans lequel un utilisateur peut saisir du texte
Le widget TextInput fournit un champ dans lequel les utilisateurs peuvent saisir du texte. Le widget accepte les suggestions, qui aident les utilisateurs à saisir des données uniformes, et les actions en cas de modification, qui sont des Actions exécutées lorsqu'une modification se produit dans le champ de saisie de texte (par exemple, lorsqu'un utilisateur ajoute ou supprime du texte).
Lorsque vous devez collecter des données abstraites ou inconnues auprès d'utilisateurs, utilisez ce widget TextInput. Pour collecter des données définies auprès des utilisateurs, utilisez plutôt le widget SelectionInput.
Pour traiter le texte saisi par les utilisateurs, consultez Recevoir les données de formulaire.
Voici une fiche composée d'un widget TextInput:
Permettre à l'utilisateur de choisir une date et une heure
Le widget DateTimePicker permet aux utilisateurs de saisir une date, une heure ou les deux. 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 valides, le sélecteur affiche une erreur qui les invite à saisir les informations correctement.
Pour traiter les valeurs de date et d'heure saisies par les utilisateurs, consultez la section Recevoir les données du formulaire.
Vous trouverez ci-dessous une fiche comportant trois types différents de widgets DateTimePicker:
Valider les données saisies dans les fiches
Cette page explique comment valider les données saisies dans le action et les widgets d'une fiche.
Par exemple, vous pouvez vérifier qu'un champ de saisie de texte contient du texte saisi par l'utilisateur ou qu'il contient un certain nombre de caractères.
Définir les widgets requis pour les actions
Dans le action de la fiche, ajoutez les noms des widgets nécessaires à une action à 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 de la fiche sont requis par 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 le champ de validation du widget textInput, vous pouvez spécifier la limite de caractères et le type d'entrée pour ce widget d'entrée 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 une fiche Google Chat renvoie une erreur, l'interface Chat affiche le message "Une erreur s'est produite". ou "Impossible de traiter votre demande." Parfois, l'UI Chat n'affiche aucun message d'erreur, mais que l'application ou la fiche Chat produit un résultat inattendu (par exemple, un message de fiche ne s'affiche pas).
Même s'il est possible qu'un message d'erreur ne s'affiche pas 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 concernant l'affichage, le débogage et la correction des erreurs, consultez Dépanner et corriger les erreurs dans Google Chat.