Suggerimenti di completamento automatico per gli input di testo

Il widget Input di testo consente al componente aggiuntivo di leggere e reagire al testo fornito dagli utenti. Puoi configurare questi widget per fornire agli utenti suggerimenti automatici per il testo di input.

I suggerimenti forniti possono provenire da un elenco statico di stringhe che fornisci. In alternativa, puoi creare i suggerimenti dal contesto, ad esempio dal testo che l'utente ha già digitato nel widget.

Configurazione dei suggerimenti

Per configurare i suggerimenti per un input di testo, devi solo svolgere le seguenti operazioni:

  • Crea un elenco di suggerimenti in base a:
    • Creazione di un elenco statico e/o
    • Definizione di un'azione con una funzione di callback che crea l'elenco in modo dinamico dal contesto.
  • Allega l'elenco di suggerimenti e/o l'azione al widget di inserimento del testo.

Se fornisci sia un elenco statico di suggerimenti sia un'azione, l'interfaccia utente dell'applicazione utilizza l'elenco statico finché l'utente non inizia a inserire caratteri, dopodiché viene utilizzata la funzione di callback e l'elenco statico viene ignorato.

Suggerimenti statici

Per offrire un elenco statico di suggerimenti, devi solo:

  1. Crea un oggetto Suggestions.
  2. Aggiungi ogni suggerimento statico utilizzando addSuggestion() o addSuggestions().
  3. Collega l'oggetto Suggestions al widget utilizzando TextInput.setSuggestions().

L'interfaccia utente mostra i suggerimenti statici nell'ordine in cui sono stati aggiunti. L'interfaccia utente esegue anche automaticamente la corrispondenza del prefisso senza distinzione tra maiuscole e minuscole e filtra l'elenco dei suggerimenti man mano che l'utente digita i caratteri nel widget.

Azioni del suggerimento

Se non utilizzi un elenco di suggerimenti statici, devi definire un'azione per creare i suggerimenti in modo dinamico. A tale scopo procedi nel seguente modo:

  1. Crea un oggetto Action e associalo a una funzione di callback che definisci.
  2. Chiama la funzione TextInput.setSuggestionsAction() del widget, fornendogli l'oggetto Action.
  3. Implementa la funzione di callback per creare l'elenco di suggerimenti e restituire un oggetto SuggestionsResponse creato.

La UI chiama la funzione di callback ogni volta che l'utente digita un carattere nell'input di testo, ma solo dopo che l'utente ha smesso di digitare per un momento. La funzione di callback riceve un oggetto evento contenente informazioni sui widget della scheda aperta. Per maggiori dettagli, vedi Oggetti evento azione.

La funzione di callback deve restituire un oggetto SuggestionsResponse valido contenente l'elenco dei suggerimenti da visualizzare. L'interfaccia utente mostra i suggerimenti nell'ordine in cui vengono aggiunti. A differenza degli elenchi statici, la UI non esegue alcun filtro automatico dei suggerimenti di richiamata in base all'input dell'utente. Se vuoi eseguire questo tipo di filtraggio, devi leggere il valore di input di testo dall'oggetto evento e filtrare i suggerimenti durante la creazione dell'elenco.

Esempio

Il seguente snippet di codice del componente aggiuntivo Google Workspace mostra come configurare i suggerimenti su due diversi widget di input di testo, il primo con un elenco statico e il secondo utilizzando una funzione di callback:

// 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!
 }

Suggerimenti e OnChangeAction()

I widget di input di testo possono avere una setOnChangeAction() funzione di gestione definita che viene eseguita ogni volta che il widget perde lo stato attivo. Se sia questo gestore che i suggerimenti sono abilitati per lo stesso input di testo, le seguenti regole definiscono il comportamento di interazione dell'input di testo:

  1. Il gestore setOnChangeAction() viene eseguito dopo la selezione di un suggerimento.
  2. Se l'utente preme Invio (o in altro modo fa perdere il focus all'input di testo) senza modificare il suggerimento selezionato, setOnChangeAction() non viene attivato di nuovo.
  3. setOnChangeAction() viene attivato di nuovo se l'utente, dopo aver selezionato un suggerimento, lo modifica in modo che non corrisponda più a nessuno dei suggerimenti nell'elenco.
  4. Se l'utente non seleziona un suggerimento, setOnChangeAction() viene attivato quando la messa a fuoco viene persa nell'input di testo.