Suggestions de saisie semi-automatique pour la saisie de texte

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

Le widget Saisie de texte permet à votre module complémentaire de lire et de réagir au texte fourni par les utilisateurs. Vous pouvez configurer ces widgets pour fournir aux utilisateurs des suggestions automatiques pour le texte saisi.

Les suggestions fournies peuvent provenir d'une liste statique de chaînes que vous fournissez. Vous pouvez également créer des suggestions à partir du contexte, par exemple le texte que l'utilisateur a déjà saisi dans le widget.

Configuration des suggestions

Pour configurer des suggestions pour une saisie de texte, procédez comme suit:

  • Pour créer une liste de suggestions :
    • Créer une liste statique
    • Définir une action avec une fonction de rappel qui génère cette liste dynamiquement à partir du contexte
  • Associez la liste de suggestions et/ou l'action au widget de saisie de texte.

Si vous fournissez à la fois une liste statique de suggestions et une action, l'interface utilisateur de l'application utilise la liste statique jusqu'à ce que l'utilisateur commence à saisir des caractères, après quoi la fonction de rappel est utilisée et la liste statique est ignorée.

Suggestions statiques

Pour proposer une liste statique de suggestions, procédez comme suit:

  1. Créez un objet Suggestions.
  2. Ajoutez-leur chaque suggestion statique à l'aide de addSuggestion() ou addSuggestions().
  3. Associez l'objet Suggestions au widget à l'aide de TextInput.setSuggestions().

L'interface utilisateur affiche les suggestions statiques dans l'ordre dans lequel elles ont été ajoutées. L'interface utilisateur effectue également automatiquement une mise en correspondance des préfixes non sensibles à la casse et filtre la liste de suggestions à mesure que l'utilisateur saisit des caractères dans le widget.

Actions sur les suggestions

Si vous n'utilisez pas une liste de suggestions statiques, vous devez définir une action pour générer vos suggestions de manière dynamique. Pour ce faire, procédez comme suit :

  1. Créez un objet Action et associez-le à une fonction de rappel que vous définissez.
  2. Appelez la fonction TextInput.setSuggestionsAction() du widget, qui lui fournit l'objet Action.
  3. Implémentez la fonction de rappel pour créer la liste des suggestions et renvoyer un objet SuggestionsResponse compilé.

L'interface utilisateur appelle la fonction de rappel chaque fois que l'utilisateur saisit un caractère dans la saisie de texte, mais seulement après qu'il a cessé de saisir du texte. La fonction de rappel reçoit un objet d'événement contenant des informations sur les widgets de la carte ouverte. Pour en savoir plus, consultez Objets d'événement d'action.

La fonction de rappel doit renvoyer un objet SuggestionsResponse valide contenant la liste des suggestions à afficher. L'interface utilisateur affiche les suggestions dans leur ordre d'ajout. Contrairement aux listes statiques, l'interface utilisateur n'effectue pas de filtrage automatique des suggestions de rappel en fonction de l'entrée utilisateur. Pour appliquer un tel filtrage, vous devez lire la valeur d'entrée du texte à partir de l'objet événement et filtrer les suggestions lors de la création de la liste.

Exemple

L'extrait de code complémentaire Google Workspace suivant montre comment configurer les suggestions sur deux widgets de saisie de texte différents, le premier avec une liste statique et le second à l'aide d'une fonction de rappel:

// Create an input with a static suggestion list.
var textInput1 = CardService.newTextInput()
    .setFieldName('colorInput')
    .setTitle('Color choice')
    .setSuggestions(CardService.newSuggestions()
        .addSuggestion('Red')
        .addSuggestion('Yellow')
        .addSuggestions(['Blue', 'Black', 'Green']));

// Create an input with a dynamic suggestion list.
var action = CardService.newAction()
    .setFunctionName('refreshSuggestions');
var textInput2 = CardService.newTextInput()
    .setFieldName('emailInput')
    .setTitle('Email')
    .setSuggestionsAction(action);

// ...

/**
 *  Build and return a suggestion response. In this case, the suggestions
 *  are a list of emails taken from the To: and CC: lists of the open
 *  message in Gmail, filtered by the text that the user has already
 *  entered. This method assumes the Google Workspace
 *  add-on extends Gmail; the add-on only calls this method for cards
 *  displayed when the user has entered a message context.
 *
 *  @param {Object} e the event object containing data associated with
 *      this text input widget.
 *  @return {SuggestionsResponse}
 */
 function refreshSuggestions(e) {
   // Activate temporary Gmail scopes, in this case so that the
   // open message metadata can be read.
   var accessToken = e.gmail.accessToken;
   GmailApp.setCurrentMessageAccessToken(accessToken);

   var userInput = e && e.formInput['emailInput'].toLowerCase();
   var messageId = e.gmail.messageId;
   var message = GmailApp.getMessageById(messageId);

   // Combine the comma-separated returned by these methods.
   var addresses = message.getTo() + ',' + message.getCc();

   // Filter the address list to those containing the text the user
   // has already entered.
   var suggestionList = [];
   addresses.split(',').forEach(function(email) {
     if (email.toLowerCase().indexOf(userInput) !== -1) {
       suggestionList.push(email);
     }
   });
   suggestionList.sort();

   return CardService.newSuggestionsResponseBuilder()
       .setSuggestions(CardService.newSuggestions()
           .addSuggestions(suggestionList))
       .build();  // Don't forget to build the response!
 }

Suggestions et OnChangeAction()

Les widgets de saisie de texte peuvent avoir une fonction de gestionnaire setOnChangeAction() définie qui s'exécute chaque fois que le widget n'est plus sélectionné. Si ce gestionnaire et les suggestions sont activés pour la même entrée de texte, les règles suivantes définissent le comportement d'interaction de la saisie de texte:

  1. Le gestionnaire setOnChangeAction() s'exécute après la sélection d'une suggestion.
  2. Si l'utilisateur appuie sur la touche Entrée (ou supprime le curseur de la saisie de texte) sans modifier la suggestion sélectionnée, setOnChangeAction() ne se déclenche pas à nouveau.
  3. setOnChangeAction() se déclenche à nouveau si l'utilisateur, après avoir sélectionné une suggestion, la modifie afin qu'elle ne corresponde plus à aucune des suggestions de la liste.
  4. Si l'utilisateur ne sélectionne aucune suggestion, setOnChangeAction() se déclenche lorsque l'entrée de texte n'est plus sélectionnée.