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 in modo da 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 il testo che l'utente ha già digitato nel widget.

Configurazione dei suggerimenti

Per configurare i suggerimenti per un input di testo, devi:

  • Crea un elenco di suggerimenti:
    • Creare un elenco statico e/o
    • La definizione di un'azione con una funzione di callback che crea un elenco dinamico in base al contesto.
  • Collega 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 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 procedere nel seguente modo:

  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 suggerimenti statici nell'ordine in cui sono stati aggiunti. Inoltre, l'interfaccia utente esegue automaticamente la corrispondenza dei prefissi senza distinzione tra maiuscole e minuscole e filtra l'elenco dei suggerimenti man mano che l'utente digita i caratteri nel widget.

Azioni sui suggerimenti

Se non utilizzi un elenco di suggerimenti statico, devi definire un'azione per generare 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, fornendo l'oggetto Action.
  3. Implementa la funzione callback per creare l'elenco di suggerimenti e restituire un oggetto SuggestionsResponse creato.

L'interfaccia utente 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 per un momento di digitare. La funzione di callback riceve un oggetto evento contenente informazioni sui widget della scheda aperta. Per maggiori dettagli, consulta Oggetti evento 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 esegue alcun filtro automatico dei suggerimenti di callback in base all'input dell'utente. Se vuoi applicare questo tipo di filtri, devi leggere il valore di input di testo dall'oggetto evento e filtrare i suggerimenti mentre crei l'elenco.

Esempio

Il seguente snippet di codice del componente aggiuntivo di Google Workspace mostra come configurare i suggerimenti su due diversi widget di input di 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()

I widget di input di testo possono avere una funzione di gestione setOnChangeAction() definita da eseguire 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 dell'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 comunque rende l'input di testo non attivo) senza modificare il suggerimento selezionato, setOnChangeAction() non si attiva 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 nessun suggerimento nell'elenco.
  4. Se l'utente non seleziona un suggerimento, setOnChangeAction() si attiva quando l'input di testo perde lo stato attivo.