Cette page a été traduite par l'API Cloud Translation.

Suggestions de saisie semi-automatique pour le texte

Widget Saisie de texte permet à votre module complémentaire de lire le texte fourni par les utilisateurs et d'y réagir. Vous pouvez configurer ces widgets pour fournir aux utilisateurs des suggestions automatiques texte d'entrée.

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

Configuration des suggestions

Pour configurer des suggestions pour une saisie de texte, il suffit d'utiliser suivantes:

Pour créer une liste de suggestions:
- créer une liste statique ; et/ou
- Définir une action avec Une fonction de rappel qui crée cette liste de manière dynamique à 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, le l'UI de l'application utilise la liste statique jusqu'à ce que l'utilisateur commence à saisir des caractères, La fonction de rappel est alors utilisée et la liste statique est ignorée.

Suggestions statiques

Pour proposer une liste statique de suggestions, il vous suffit de procéder comme suit:

Créer un Suggestions .
Ajoutez chaque suggestion statique à l'aide de addSuggestion(). ou addSuggestions().
Joindre le 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. Interface utilisateur effectue également automatiquement une correspondance des préfixes non sensibles à la casse et filtre liste de suggestions à mesure que l'utilisateur saisit des caractères dans le widget.

Actions des suggestions

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

Créer un objet Action et l'associer à une fonction de rappel que vous définissez.
Appelez la méthode TextInput.setSuggestionsAction() du widget. en lui fournissant la fonction Action .
Implémentez la fonction de rappel pour créer la liste de suggestions et renvoyer un SuggestionsResponse intégré .

L'interface utilisateur appelle la fonction de rappel chaque fois que l'utilisateur saisit un caractère dans le saisie de texte, mais seulement après que l'utilisateur a arrêté de saisir un moment. La de rappel reçoit un objet événement contenant des informations ouvrir les widgets de la fiche. Voir Objets d'événement d'action pour en savoir plus.

La fonction de rappel doit renvoyer une valeur SuggestionsResponse contenant la liste des suggestions à afficher. L'UI affiche dans l'ordre dans lequel elles sont ajoutées. Contrairement aux listes statiques, l'interface utilisateur Ne pas filtrer automatiquement les suggestions de rappel en fonction de l'utilisateur saisie. Pour appliquer ce filtrage, vous devez lire la valeur d'entrée de texte à partir de l'objet "événement" et filtrez vos suggestions à mesure que vous créez la liste.

Exemple

L'extrait de code suivant du module complémentaire Google Workspace montre comment configurer les suggestions sur deux widgets de saisie de texte différents, le premier avec une liste statique et le à 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 setOnChangeAction() Fonction de gestionnaire définie qui s'exécute chaque fois que le widget n'est plus actif. Si ce gestionnaire et les suggestions sont tous deux activés pour la même entrée de texte, la Les règles suivantes définissent le comportement d'interaction de saisie de texte:

Le gestionnaire setOnChangeAction() s'exécute une fois qu'une suggestion est sélectionnée.
Si l'utilisateur appuie sur Entrée (ou si la saisie de texte n'est plus au premier plan) sans modifier la suggestion sélectionnée, setOnChangeAction() ne déclencher à nouveau.
setOnChangeAction() se déclenche à nouveau si l'utilisateur, après avoir sélectionné un suggestion, la modifie afin qu'elle ne corresponde plus à aucune des suggestions de la liste.
Si l'utilisateur ne sélectionne pas de suggestion, setOnChangeAction() se déclenche lorsque l'entrée de texte n'est plus sélectionnée.