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 derivare da un elenco statico di stringhe fornite da te. In alternativa, puoi creare i suggerimenti dal contesto, come il testo già digitato dall'utente nel widget.

Configurazione dei suggerimenti

Per configurare i suggerimenti per un input di testo, è necessario svolgere le seguenti operazioni:

  • Crea un elenco di suggerimenti in questo modo:
    • Creazione di un elenco statico e/o
    • Definire un'azione con una funzione di callback che crea l'elenco in modo dinamico a partire dal contesto.
  • Allega l'elenco dei suggerimenti e/o l'azione al widget di immissione 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 i caratteri, dopodiché viene utilizzata la funzione di callback e l'elenco statico viene ignorato.

Suggerimenti statici

Per offrire un elenco statico di suggerimenti, è sufficiente:

  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. Inoltre, l'interfaccia utente esegue automaticamente una corrispondenza dei prefissi senza distinzione tra maiuscole e minuscole e filtra l'elenco di suggerimenti mentre l'utente digita caratteri nel widget.

Azioni suggerimento

Se non utilizzi un elenco di suggerimenti statico, 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 definita da te.
  2. Chiama la funzione TextInput.setSuggestionsAction() del widget, fornendo l'oggetto Action.
  3. Implementa la funzione 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 i dettagli, consulta Oggetti evento di azione.

La funzione di callback deve restituire un oggetto SuggestionsResponse valido contenente l'elenco di suggerimenti da visualizzare. L'interfaccia utente mostra i suggerimenti nell'ordine in cui vengono aggiunti. A differenza degli elenchi statici, l'interfaccia utente non filtra automaticamente i suggerimenti di callback in base all'input dell'utente. Se vuoi utilizzare questo filtro, devi leggere il valore di input di testo dell'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 immissione testo, il primo con un elenco statico e il secondo con 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()

Per i widget di input di testo è possibile definire una funzione di gestione setOnChangeAction() che viene eseguita ogni volta che il widget perde lo stato attivo. Se questo gestore e i suggerimenti sono entrambi abilitati per lo stesso input di testo, le seguenti regole definiscono il comportamento di interazione con l'input di testo:

  1. Il gestore setOnChangeAction() viene eseguito dopo la selezione di un suggerimento.
  2. Se l'utente preme Invio (o altrimenti fa perdere lo stato attivo all'input di testo) senza modificare il suggerimento selezionato, setOnChangeAction() non viene attivato di nuovo.
  3. setOnChangeAction() si attiva 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() si attiva quando l'input di testo perde lo stato attivo.