Entrée sélectionnée

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.


Créez et prévisualisez des fiches avec Card Builder.

Ouvrez l'outil de création de cartes

Le widget SelectionInput accepte les suggestions, qui aident les utilisateurs à saisir des données uniformes, et les actions en cas de modification (Actions) qui s'exécutent 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.

Exemples

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

Exemple 1: cases à cocher

Voici une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel et/ou personnel avec un widget SelectionInput utilisant des cases à cocher:

Exemple 2: cases d'option

Voici une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel ou personnel avec un widget SelectionInput utilisant des cases d'option:

Exemple 3: commutateurs

Voici une boîte de dialogue qui demande à l'utilisateur de spécifier si un contact est professionnel ou personnel avec un widget SelectionInput utilisant des contacteurs:

La boîte de dialogue suivante demande à l'utilisateur de spécifier si un contact est professionnel ou personnel avec un widget SelectionInput utilisant un menu déroulant:

Exemple 5: menu multi-sélection

La boîte de dialogue suivante affiche une demande à l'utilisateur de sélectionner des contacts dans un menu multi-sélection:

Sources de données supplémentaires pour les menus à sélection multiple

La section suivante explique comment utiliser les menus multi-sélection pour insérer 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 remplir les éléments d'un menu multi-sélection à partir des sources de données suivantes dans Google Workspace:

  • Utilisateurs de Google Workspace: vous ne pouvez ajouter des utilisateurs qu'au sein de 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 des sources de données Google Workspace, vous devez spécifier 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 des espaces Chat. Pour renseigner les espaces, l'entrée de 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 en dehors de Google Workspace

Les menus multi-sélection permettent également de renseigner 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 à faire son choix dans une liste de prospects commerciaux dans un système de gestion de la relation client (CRM).

Pour utiliser une source de données externe, utilisez le champ externalDataSource pour spécifier une fonction qui renvoie des éléments à partir de la source de données.

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 s'affichent dans le menu multi-sélection avant que les utilisateurs ne saisissent du texte dans le menu. Par exemple, vous pouvez renseigner les contacts recherchés récemment pour l'utilisateur. Pour insérer des éléments suggérés à partir d'une source de données externe, spécifiez des objets SelectionItem.

Le code suivant affiche un menu de sélection multiple contenant les éléments d'un ensemble externe de contacts pour l'utilisateur. 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 renseigne les villes des États-Unis, votre application Chat peut suggérer automatiquement Atlanta avant que l'utilisateur ne termine sa saisie. La saisie semi-automatique peut contenir jusqu'à 100 éléments.

Pour la saisie semi-automatique des éléments, vous devez créer une fonction qui interroge la source de données externe et renvoie des éléments chaque fois qu'un utilisateur saisit du texte 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.
  • Identifiez que la valeur invokedFunction de l'événement d'interaction correspond à la fonction du champ externalDataSource.
  • Lorsque les fonctions correspondent, renvoyez les é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 effectue la saisie semi-automatique des éléments d'une ressource de données externe. Dans 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 ;

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

Représentation et champs JSON

Représentation JSON
{
  "name": string,
  "label": string,
  "type": enum (SelectionType),
  "items": [
    {
      object (SelectionItem)
    }
  ],
  "onChangeAction": {
    object (Action)
  },
  "multiSelectMaxSelectedItems": integer,
  "multiSelectMinQueryLength": integer,

  // Union field multi_select_data_source can be only one of the following:
  "externalDataSource": {
    object (Action)
  },
  "platformDataSource": {
    object (PlatformDataSource)
  }
  // End of list of possible types for union field multi_select_data_source.
}
Champs
name

string

Nom qui identifie l'entrée de sélection dans un événement de saisie de formulaire.

Pour en savoir plus sur l'utilisation des entrées de formulaire, consultez Recevoir des données de formulaire.

label

string

Texte qui apparaît au-dessus du champ de saisie de sélection dans l'interface utilisateur.

Spécifiez un texte qui aide l'utilisateur à saisir les informations dont votre application a besoin. Par exemple, si les utilisateurs sélectionnent l'urgence d'une demande d'assistance dans un menu déroulant, le libellé peut être "Urgence" ou "Sélectionner l'urgence".

type

enum (SelectionType)

Type d'éléments affichés aux utilisateurs dans un widget SelectionInput. Les types de sélection prennent en charge différents types d'interactions. Par exemple, les utilisateurs peuvent cocher une ou plusieurs cases, mais ils ne peuvent sélectionner qu'une seule valeur dans un menu déroulant.

items[]

object (SelectionItem)

Tableau d'éléments sélectionnables. Par exemple, un tableau de cases d'option ou de cases à cocher. Jusqu'à 100 éléments acceptés.

onChangeAction

object (Action)

Si cette option est spécifiée, le formulaire est envoyé lorsque la sélection change. S'il n'est pas spécifié, vous devez spécifier un bouton distinct pour envoyer le formulaire.

Pour en savoir plus sur l'utilisation des entrées de formulaire, consultez Recevoir des données de formulaire.

multiSelectMaxSelectedItems

integer

Pour les menus à plusieurs sélections, nombre maximal d'éléments qu'un utilisateur peut sélectionner. La valeur minimale est de 1 article. Si aucune valeur n'est spécifiée, la valeur par défaut est trois.

multiSelectMinQueryLength

integer

Pour les menus à sélection multiple, le nombre de caractères de texte qu'un utilisateur saisit avant que l'application Chat interroge la saisie semi-automatique et affiche les éléments suggérés dans le menu.

Si aucune valeur n'est spécifiée, la valeur par défaut est 0 caractère pour les sources de données statiques et 3 caractères pour les sources de données externes.

Champ d'union multi_select_data_source. Pour un menu multi-sélection, source de données qui renseigne les éléments de sélection.

Disponible pour les applications Google Chat et indisponible pour les modules complémentaires Google Workspace. multi_select_data_source ne peut être que l'un des éléments suivants:

externalDataSource

object (Action)

une source de données externe, telle qu'une base de données relationnelles ;

platformDataSource

object (PlatformDataSource)

Une source de données Google Workspace

SelectionType

Enums
CHECK_BOX Une série de cases à cocher. Les utilisateurs peuvent cocher une ou plusieurs cases.
RADIO_BUTTON Ensemble de cases d'option. Les utilisateurs peuvent sélectionner une case d'option.
SWITCH Un ensemble d'interrupteurs. Les utilisateurs peuvent activer un ou plusieurs interrupteurs.
DROPDOWN Un menu déroulant Les utilisateurs peuvent sélectionner un élément dans le menu.
MULTI_SELECT

Menu multi-sélection pour les données statiques ou dynamiques Dans la barre de menu, les utilisateurs sélectionnent un ou plusieurs éléments. Les utilisateurs peuvent également saisir des valeurs pour insérer des données dynamiques. Par exemple, les utilisateurs peuvent commencer à saisir le nom d'un espace Google Chat, et le widget suggère automatiquement cet espace.

Pour renseigner les éléments d'un menu à sélection multiple, vous pouvez utiliser l'un des types de sources de données suivants:

  • Données statiques: les éléments sont spécifiés en tant qu'objets SelectionItem dans le widget. Jusqu'à 100 éléments.
  • Données Google Workspace: les éléments sont renseignés à l'aide de données provenant de Google Workspace, comme les utilisateurs Google Workspace ou les espaces Google Chat.
  • Données externes: les éléments sont renseignés à partir d'une source de données externe externe à Google Workspace.

Pour obtenir des exemples d'implémentation de menus multi-sélection, consultez la page du widget SelectionInput .

Disponible pour les applications Google Chat et les modules complémentaires Google Workspace. La sélection multiple est disponible pour les modules complémentaires Google Workspace.

SelectionItem

Représentation JSON
{
  "text": string,
  "value": string,
  "selected": boolean,
  "startIconUri": string,
  "bottomText": string
}
Champs
text

string

Texte qui identifie ou décrit l'élément pour les utilisateurs.

value

string

Valeur associée à cet élément. Le client doit l'utiliser comme valeur d'entrée de formulaire.

Pour en savoir plus sur l'utilisation des entrées de formulaire, consultez Recevoir des données de formulaire.

selected

boolean

Indique si l'élément est sélectionné par défaut. Si le champ de sélection n'accepte qu'une seule valeur (pour les cases d'option ou les menus déroulants, par exemple), ne définissez ce champ que pour un seul élément.

startIconUri

string

Pour les menus à sélection multiple, URL de l'icône affichée à côté du champ text de l'élément. Les fichiers PNG et JPEG sont acceptés. Doit être une URL HTTPS. Exemple : https://developers.google.com/chat/images/quickstart-app-avatar.png.

bottomText

string

Pour les menus multi-sélection, une description textuelle ou un libellé affiché sous le champ text de l'élément.

Action

Action décrivant le comportement lors de l'envoi du formulaire. Par exemple, vous pouvez appeler un script Apps Script pour gérer le formulaire. Si l'action est déclenchée, les valeurs du formulaire sont envoyées au serveur.

Disponible pour les applications Google Chat et les modules complémentaires Google Workspace.

Représentation JSON
{
  "function": string,
  "parameters": [
    {
      object (ActionParameter)
    }
  ],
  "loadIndicator": enum (LoadIndicator),
  "persistValues": boolean,
  "interaction": enum (Interaction)
}
Champs
function

string

Fonction personnalisée à invoquer lorsque l'utilisateur clique sur l'élément conteneur ou est activé en continu.

Pour obtenir un exemple d'utilisation, consultez la section Créer des fiches interactives.

parameters[]

object (ActionParameter)

Liste des paramètres d'action.

loadIndicator

enum (LoadIndicator)

Spécifie l'indicateur de chargement que l'action affiche lors de l'appel à l'action.

persistValues

boolean

Indique si les valeurs du formulaire sont conservées après l'action. La valeur par défaut est false.

Si la valeur est true, les valeurs du formulaire restent après le déclenchement de l'action. Pour permettre à l'utilisateur d'effectuer des modifications pendant le traitement de l'action, définissez LoadIndicator sur NONE. Pour les messages sous forme de fiches dans les applications Chat, vous devez également définir ResponseType de l'action sur UPDATE_MESSAGE et utiliser le même cardId que celui figurant sur la fiche contenant l'action.

Si la valeur est false, les valeurs du formulaire sont effacées lorsque l'action est déclenchée. Pour empêcher l'utilisateur d'apporter des modifications pendant le traitement de l'action, définissez LoadIndicator sur SPINNER.

interaction

enum (Interaction)

Facultatif. Obligatoire lors de l'ouverture d'une boîte de dialogue.

Que faire en réponse à une interaction avec un utilisateur (par exemple, lorsqu'il clique sur un bouton dans un message de fiche) ?

Si aucune valeur n'est spécifiée, l'application répond en exécutant normalement un action (comme l'ouverture d'un lien ou l'exécution d'une fonction).

Si vous spécifiez un interaction, l'application peut répondre de manière interactive spéciale. Par exemple, en définissant interaction sur OPEN_DIALOG, l'application peut ouvrir une boîte de dialogue. Si cet indicateur est spécifié, aucun indicateur de chargement ne s'affiche. Si elle est spécifiée pour un module complémentaire, la fiche entière est supprimée et rien n'est affiché dans le client.

Disponible pour les applications Google Chat et indisponible pour les modules complémentaires Google Workspace.

ActionParameter

Liste des paramètres de chaîne à fournir lorsque la méthode d'action est appelée. Prenons l'exemple de trois boutons Répéter: Répéter maintenant, Répéter un jour ou Répéter la semaine suivante. Vous pouvez utiliser action method = snooze() pour transmettre le type et la durée de mise en pause dans la liste des paramètres de chaîne.

Pour en savoir plus, consultez CommonEventObject.

Disponible pour les applications Google Chat et les modules complémentaires Google Workspace.

Représentation JSON
{
  "key": string,
  "value": string
}
Champs
key

string

Nom du paramètre du script d'action.

value

string

Valeur du paramètre.

LoadIndicator

Spécifie l'indicateur de chargement que l'action affiche lors de l'appel à l'action.

Disponible pour les applications Google Chat et les modules complémentaires Google Workspace.

Enums
SPINNER Affiche une icône de chargement pour indiquer que le contenu est en cours de chargement.
NONE Rien ne s'affiche.

Interaction

Facultatif. Obligatoire lors de l'ouverture d'une boîte de dialogue.

Que faire en réponse à une interaction avec un utilisateur (par exemple, lorsqu'il clique sur un bouton dans un message de fiche) ?

Si aucune valeur n'est spécifiée, l'application répond en exécutant normalement un action (comme l'ouverture d'un lien ou l'exécution d'une fonction).

Si vous spécifiez un interaction, l'application peut répondre de manière interactive spéciale. Par exemple, en définissant interaction sur OPEN_DIALOG, l'application peut ouvrir une boîte de dialogue.

Si cet indicateur est spécifié, aucun indicateur de chargement ne s'affiche. Si elle est spécifiée pour un module complémentaire, la fiche entière est supprimée et rien n'est affiché dans le client.

Disponible pour les applications Google Chat et indisponible pour les modules complémentaires Google Workspace.

Enums
INTERACTION_UNSPECIFIED Valeur par défaut. Le action s'exécute normalement.
OPEN_DIALOG

Ouvre une boîte de dialogue, une interface fenêtre sous forme de fiches, que les applications Chat utilisent pour interagir avec les utilisateurs.

Uniquement compatible avec les applications Chat en réponse à des clics sur des boutons dans les messages des fiches. Si elle est spécifiée pour un module complémentaire, la fiche entière est supprimée et rien n'est affiché dans le client.

Disponible pour les applications Google Chat et indisponible pour les modules complémentaires Google Workspace.

Dépannage

Lorsqu'une application ou une fiche Google Chat renvoie une erreur, l'interface Chat affiche un message indiquant "Un problème est survenu" ou "Impossible de traiter votre demande". Il peut arriver que l'interface Chat n'affiche aucun message d'erreur, mais que l'application ou la fiche Chat génère un résultat inattendu. Par exemple, il est possible qu'un message de fiche ne s'affiche pas.

Bien qu'aucun message d'erreur ne s'affiche dans l'interface Chat, des messages d'erreur descriptifs et des données de journal sont disponibles pour vous aider à corriger les erreurs lorsque la journalisation des erreurs est activée pour les applications Chat. Si vous avez besoin d'aide pour afficher, déboguer et corriger les erreurs, consultez Résoudre les erreurs Google Chat.