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 fiches pour que les utilisateurs puissent interagir avec votre application Google Chat, par exemple en cliquant sur un bouton ou en envoyant 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, qui sont des fiches qui s'affichent dans l'onglet Accueil des messages privés avec l'application Chat.
  • Boîtes de dialogue, qui sont des fiches s'ouvrant dans une nouvelle fenêtre à partir de messages et de pages d'accueil.

Lorsque les utilisateurs interagissent avec des fiches, les applications Chat peuvent utiliser les données qu'elles 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 les messages et les interfaces utilisateur des applications Chat :

Ouvrir le générateur de fiches

Prérequis

Une application Google Chat configurée pour recevoir des interactions utilisateur et y répondre. Pour créer une application Chat interactive, suivez l'un des guides de démarrage rapide suivants en fonction de l'architecture d'application que vous souhaitez utiliser :

Ajouter un bouton

Le widget ButtonList affiche un ensemble de boutons. Les boutons peuvent afficher du texte, une icône, ou les deux. Chaque Button accepte une action OnClick qui se produit lorsque les utilisateurs cliquent sur le bouton. Exemple :

  • Ouvrir un lien hypertexte avec OpenLink pour fournir des informations supplémentaires aux utilisateurs.
  • Exécutez un action qui exécute une fonction personnalisée, comme l'appel d'une API.

Pour l'accessibilité, les boutons sont compatibles avec le 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 ouvre la documentation pour les développeurs Google Chat 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".

Ajouter un bouton avec le style Material Design

L'exemple suivant affiche un ensemble de boutons dans différents styles de boutons Material Design.

Pour appliquer le style Material Design, n'incluez pas l'attribut "color".

Ajouter 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".

L'exemple suivant affiche une fiche composée d'un widget ButtonList avec deux boutons. Un bouton 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

Le code suivant affiche 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 de 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

L'exemple suivant affiche 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 sur le bouton de texte pour exécuter la fonction sendEmail.

Personnaliser le bouton d'une section réductible

Personnalisez le bouton de contrôle qui réduit et agrandit les sections d'une fiche. Vous pouvez choisir parmi plusieurs icônes ou images pour représenter visuellement le contenu de la section, afin d'aider les utilisateurs à comprendre les informations et à s'en servir.

Ajouter un menu à développer

Le Overflow menu peut être utilisé dans les fiches Chat pour offrir d'autres options et actions. Il vous permet d'inclure plus d'options sans encombrer l'interface de la fiche, pour un design épuré et organisé.

Ajouter une liste de chips

Le widget ChipList offre un moyen polyvalent et visuellement attrayant d'afficher des informations. Utilisez les listes de chips pour représenter des tags, des catégories ou d'autres données utiles, et faciliter ainsi la navigation et l'interaction avec vos contenus pour les utilisateurs.

Collecter des informations auprès des utilisateurs

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

Pour savoir comment traiter les entrées des 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. Le widget accepte les suggestions, qui aident les utilisateurs à saisir des données uniformes, et les actions 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 des utilisateurs, utilisez ce widget TextInput. Pour collecter des données définies auprès des utilisateurs, utilisez plutôt le widget SelectionInput.

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

Collecter des dates ou des heures

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

L'exemple suivant affiche une fiche composée de trois types de widgets DateTimePicker différents :

Permettre aux utilisateurs de sélectionner des éléments

Le widget SelectionInput fournit un ensemble d'éléments sélectionnables, tels que des cases à cocher, des cases d'option, des boutons d'activation/de désactivation 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 de modification, qui sont des 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 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 fiches qui utilisent le widget SelectionInput. Les exemples utilisent différents types d'entrées de section :

Ajouter une case à cocher

L'image suivante affiche une fiche qui demande à l'utilisateur de spécifier si un contact est professionnel, personnel ou les deux, avec un widget SelectionInput qui utilise des cases à cocher :

Ajouter une case d'option

L'exemple suivant affiche une fiche qui demande à l'utilisateur de spécifier si un contact est professionnel ou personnel à l'aide d'un widget SelectionInput qui utilise des cases d'option :

Ajouter un bouton bascule

L'image suivante montre une fiche qui demande à l'utilisateur de spécifier si un contact est professionnel, personnel ou les deux, à l'aide d'un widget SelectionInput qui utilise des boutons bascule :

L'exemple suivant affiche une fiche qui demande à l'utilisateur de préciser si un contact est professionnel ou personnel, à l'aide d'un widget SelectionInput qui utilise un menu déroulant :

Remplir dynamiquement les menus déroulants

Disponible pour les applications Google Chat.

Vous pouvez remplir dynamiquement les éléments d'un menu déroulant à partir de sources de données dans Google Workspace ou d'une source de données externe. Pour utiliser des sources de données dynamiques, vous devez spécifier le champ dataSourceConfigs, qui est un tableau d'objets DataSourceConfig. Chaque DataSourceConfig peut contenir un platformDataSource ou un remoteDataSource. Seul un DataSourceConfig est accepté pour le moment.

Remplir des éléments à partir de Google Workspace

Pour renseigner des éléments à partir de sources de données Google Workspace, telles que des utilisateurs Google Workspace, vous devez spécifier le champ platformDataSource dans un DataSourceConfig. Contrairement à l'utilisation d'un items statique, vous omettez les objets SelectionItem, car ces éléments de sélection proviennent de manière dynamique de Google Workspace.

Le code suivant montre un menu déroulant qui renseigne les utilisateurs Google Workspace :

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "dataSourceConfigs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "minCharactersTrigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}
Remplir des éléments à partir d'une source de données externe

Pour renseigner des éléments à partir d'une source de données tierce ou externe, telle qu'un système de gestion de la relation client (CRM), vous utilisez le champ remoteDataSource dans un DataSourceConfig pour spécifier une fonction qui renvoie des éléments de la source de données.

Le code suivant montre un menu déroulant qui renseigne les éléments d'un ensemble externe de contacts en exécutant la fonction getCrmLeads :

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "dataSourceConfigs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "minCharactersTrigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

Pour réduire le nombre de requêtes adressées à une source de données dynamique, vous pouvez inclure des éléments suggérés qui s'affichent dans le menu déroulant avant que les utilisateurs ne saisissent du texte. Vous pouvez également configurer la liste déroulante pour qu'elle complète automatiquement les éléments en fonction de ce que les utilisateurs saisissent en définissant minCharactersTrigger dans DataSourceConfig. Lorsqu'un utilisateur saisit au moins le nombre de caractères spécifié dans minCharactersTrigger, la fonction spécifiée dans remoteDataSource est déclenchée. L'objet d'événement transmis à votre fonction inclut l'entrée de l'utilisateur dans la clé autocomplete_widget_query.

Ajouter un menu de sélection multiple

L'exemple suivant affiche une fiche qui demande à l'utilisateur de sélectionner des contacts dans un menu à sélection multiple :

Vous pouvez renseigner les éléments d'un menu à sélection multiple à partir des sources de données suivantes dans Google Workspace :

  • Utilisateurs Google Workspace : vous ne pouvez ajouter que des utilisateurs de la même organisation Google Workspace.
  • Espaces Chat : l'utilisateur qui saisit des éléments dans le menu à sélection multiple ne peut afficher et sélectionner que les espaces auxquels il appartient au sein de 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 SelectionItem, car ces éléments de sélection proviennent de manière dynamique de Google Workspace.

Le code suivant montre un menu à sélection multiple 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 de sélection multiple d'espaces Chat. Pour renseigner les espaces, l'entrée de sélection spécifie le champ hostAppDataSource. Le menu de sélection multiple 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
          }
        }
      }
    }
  }
}

Les menus à sélection multiple peuvent également 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 à sélectionner des éléments dans une liste de leads commerciaux d'un système de gestion de la relation client (CRM).

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

Pour réduire les requêtes adressées à une source de données externe, vous pouvez inclure des éléments suggérés qui s'affichent dans le menu de sélection multiple avant que les utilisateurs ne saisissent du texte dans le menu. Par exemple, vous pouvez renseigner les contacts récemment recherchés pour l'utilisateur. Pour renseigner les éléments suggérés à partir d'une source de données externe, spécifiez des objets SelectionItem.

L'exemple de code suivant montre un menu à sélection multiple qui interroge et renseigne des éléments à partir d'une source de données externe :

Node.js

node/chat/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: FUNCTION_URL },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

Remplacez FUNCTION_URL par le point de terminaison HTTP qui interroge la source de données externe.

Python

python/chat/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': FUNCTION_URL },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_suggested_contact("3")]
}

Remplacez FUNCTION_URL par le point de terminaison HTTP qui interroge la source de données externe.

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

Remplacez FUNCTION_URL par le point de terminaison HTTP qui interroge la source de données externe.

Apps Script

Cet exemple envoie un message de fiche en renvoyant un fichier JSON de fiche. Vous pouvez également utiliser le service de fiches Apps Script.

apps-script/chat/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "queryContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

Remplir les éléments suggérés à partir d'une source de données dynamique

Pour les sources de données externes, vous pouvez également compléter automatiquement et suggérer des éléments que les utilisateurs commencent à saisir dans un menu à sélection multiple ou un menu déroulant. 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. Vous pouvez suggérer jusqu'à 100 articles.

Pour renvoyer des éléments suggérés, la fonction qui interroge la source de données externe doit effectuer les opérations suivantes :

  1. Gérer un objet d'événement, que l'application Chat reçoit lorsque les utilisateurs saisissent du texte dans le menu.
  2. À partir de l'objet d'événement, récupérez la valeur saisie par l'utilisateur, qui est représentée dans le champ event.commonEventObject.parameters["autocomplete_widget_query"].
  3. Interrogez la source de données à l'aide de la valeur saisie par l'utilisateur pour obtenir un ou plusieurs SelectionItems à suggérer à l'utilisateur.
  4. Renvoyez les éléments suggérés en renvoyant l'action RenderActions avec un objet modifyCard.

L'exemple de code suivant montre comment une application Chat suggère de manière dynamique des éléments dans le menu de sélection multiple d'une fiche. Lorsqu'un utilisateur saisit du texte dans le menu, la fonction ou le point de terminaison fourni dans le champ externalDataSource du widget interroge une source de données externe et suggère des éléments que l'utilisateur peut sélectionner :

Node.js

node/chat/selection-input/index.js
/**
 * Web app that responds to events sent from a Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: FUNCTION_URL },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
});

/**
 * Get contact suggestions based on text typed by users.
 *
 * @param {Object} event the event object that contains the user's query
 * @return {Object} suggestions
 */
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Remplacez FUNCTION_URL par le point de terminaison HTTP qui interroge la source de données externe.

Python

python/chat/selection-input/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': {
    'message': { 'cardsV2': [{
      'cardId': "contactSelector",
      'card': { 'sections':[{ 'widgets': [{
        'selectionInput': {
          'name': "contacts",
          'type': "MULTI_SELECT",
          'label': "Selected contacts",
          'multiSelectMaxSelectedItems': 3,
          'multiSelectMinQueryLength': 1,
          'externalDataSource': { 'function': FUNCTION_URL },
          # Suggested items loaded by default.
          # The list is static here but it could be dynamic.
          'items': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Remplacez FUNCTION_URL par le point de terminaison HTTP qui interroge la source de données externe.

Java

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // The list is static here but it could be dynamic.
      getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
    // Only return items based on the query from the user
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

  /**
   * Generate a suggested contact given an ID.
   * 
   * @param id The ID of the contact to return.
   * @return The contact formatted as a selection item in the menu.
   */
  GoogleAppsCardV1SelectionItem getSuggestedContact(String id) {
    return new GoogleAppsCardV1SelectionItem()
      .setValue(id)
      .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
      .setText("Contact " + id);
  }
}

Remplacez FUNCTION_URL par le point de terminaison HTTP qui interroge la source de données externe.

Apps Script

Cet exemple envoie un message de fiche en renvoyant un fichier JSON de fiche. Vous pouvez également utiliser le service de fiches Apps Script.

apps-script/chat/selection-input/selection-input.gs
/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Valider les données saisies dans les fiches

Cette page explique comment valider les données saisies dans les widgets et le action 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 champ action de la fiche, ajoutez 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 de formulaire est annulé.

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

Définir une action allWidgetsAreRequired dans la sélection multiple

JSON

{
  "sections": [
    {
      "header": "Select contacts",
      "widgets": [
        {
          "selectionInput": {
            "type": "MULTI_SELECT",
            "label": "Selected contacts",
            "name": "contacts",
            "multiSelectMaxSelectedItems": 3,
            "multiSelectMinQueryLength": 1,
            "onChangeAction": {
              "allWidgetsAreRequired": 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 allWidgetsAreRequired 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":{
              "allWidgetsAreRequired": 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éfinir une action allWidgetsAreRequired dans le menu déroulant

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "collapsible": true,
      "uncollapsibleWidgetsCount": 1,
      "widgets": [
        {
          "selectionInput": {
            "name": "location",
            "label": "Select Color",
            "type": "DROPDOWN",
            "onChangeAction": {
              "allWidgetsAreRequired": 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, 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 un nombre maximal 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": {"characterLimit": 15},
            "onChangeAction":{
              "allWidgetsAreRequired": 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": {
              "inputType": "EMAIL"
            },
            "onChangeAction": {
              "allWidgetsAreRequired": true
            }
          }
        },
        {
          "textInput": {
            "name": "validate_integer",
            "label": "Please enter a number",
              "type": "SINGLE_LINE",
            "validation": {
              "inputType": "INTEGER"
            }
          }
        },
        {
          "textInput": {
            "name": "validate_float",
            "label": "Please enter a number with a decimal",
            "type": "SINGLE_LINE",
            "validation": {
              "inputType": "FLOAT"
            }
          }
        }
      ]
    }
  ]
}

Résoudre les problèmes

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

Même si aucun message d'erreur ne s'affiche dans l'UI de 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. Pour obtenir de l'aide pour afficher, déboguer et corriger les erreurs, consultez Résoudre les erreurs Google Chat.

Applications Chat qui ne sont pas des modules complémentaires : concevoir des fiches et des boîtes de dialogue interactives

La documentation suivante s'applique aux applications Chat qui ne sont pas des modules complémentaires Google Workspace. Pour migrer une application Chat qui n'est pas un module complémentaire, consultez Convertir une application Google Chat en module complémentaire Google Workspace.

Le code suivant montre un menu de sélection multiple d'éléments d'un ensemble externe de contacts pour l'utilisateur dans une application Chat qui n'est pas un module complémentaire. Le menu affiche un contact par défaut et exécute la fonction getContacts pour récupérer et renseigner les éléments de la source de données externe :

Node.js

node/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Python

python/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': "getContacts" },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_contact("3")]
}

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction("getContacts"))
  .setItems(List.of(getContact("3")))))))))));

Apps Script

apps-script/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "getContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getContact("3")]
}

Pour la saisie semi-automatique des éléments dans une application Chat qui n'est pas un module complémentaire, créez 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 de sélection multiple. 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 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, récupérez la valeur de la clé autocomplete_widget_query. Cette valeur représente ce que l'utilisateur saisit dans le menu.

Le code suivant complète automatiquement les éléments d'une ressource de données externe. En reprenant l'exemple précédent, l'application Chat qui n'est pas un module complémentaire suggère des éléments en fonction du moment où la fonction getContacts est déclenchée :

Node.js

node/selection-input/index.js
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

Python

python/selection-input/main.py
def on_widget_update(event: dict) -> dict:
  """Responds to a WIDGET_UPDATE event in Google Chat."""
  if "getContacts" == event.get("common").get("invokedFunction"):
    query = event.get("common").get("parameters").get("autocomplete_widget_query")
    return { 'actionResponse': {
      'type': "UPDATE_WIDGET",
      'updatedWidget': { 'suggestions': { 'items': list(filter(lambda e: query is None or query in e["text"], [
        # The list is static here but it could be dynamic.
        get_contact("1"), get_contact("2"), get_contact("3"), get_contact("4"), get_contact("5")
      # Only return items based on the query from the user
      ]))}}
    }}


def get_contact(id: str) -> dict:
  """Generate a suggested contact given an ID."""
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

Java

java/selection-input/src/main/java/com/google/chat/selectionInput/App.java
// Responds to a WIDGET_UPDATE event in Google Chat.
Message onWidgetUpdate(JsonNode event) {
  if ("getContacts".equals(event.at("/invokedFunction").asText())) {
    String query = event.at("/common/parameters/autocomplete_widget_query").asText();
    return new Message().setActionResponse(new ActionResponse()
      .setType("UPDATE_WIDGET")
      .setUpdatedWidget(new UpdatedWidget()
        .setSuggestions(new SelectionItems().setItems(List.of(
          // The list is static here but it could be dynamic.
          getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
        // Only return items based on the query from the user
        ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList()))));
  }
  return null;
}

// Generate a suggested contact given an ID.
GoogleAppsCardV1SelectionItem getContact(String id) {
  return new GoogleAppsCardV1SelectionItem()
    .setValue(id)
    .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
    .setText("Contact " + id);
}

Apps Script

apps-script/selection-input/selection-input.gs
/**
 * Responds to a WIDGET_UPDATE event in Google Chat.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app.
 */
function onWidgetUpdate(event) {
  if (event.common["invokedFunction"] === "getContacts") {
    const query = event.common.parameters["autocomplete_widget_query"];
    return { actionResponse: {
      type: "UPDATE_WIDGET",
      updatedWidget: { suggestions: { items: [
        // The list is static here but it could be dynamic.
        getContact("1"), getContact("2"), getContact("3"), getContact("4"), getContact("5")
      // Only return items based on the query from the user
      ].filter(e => !query || e.text.includes(query))}}
    }};
  }
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a suggested item for selectors.
 */
function getContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}