Suggerimenti di completamento automatico per gli input di testo

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

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.

Configurare i suggerimenti

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

  • Crea un elenco di suggerimenti per:
    • Creazione di un elenco statico e/o
    • Definire un'azione con una funzione di callback che genera l'elenco dinamicamente dal contesto.
  • Collega l'elenco di suggerimenti e/o l'azione al widget di immissione di 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, quando 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. La UI esegue anche 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 di 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 che definisci.
  2. Chiama la funzione TextInput.setSuggestionsAction() del widget, fornendo l'oggetto Action.
  3. Implementa la funzione di callback per creare l'elenco di suggerimenti e restituire un oggetto SuggestionsResponse.

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 di digitare per un momento. La funzione callback riceve un oggetto evento contenente informazioni sui widget della scheda aperta. Per maggiori dettagli, consulta Oggetti evento di azioni.

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, l'interfaccia utente non applica alcun filtro automatico ai suggerimenti di chiamata in base all'input dell'utente. Se vuoi applicare questo tipo di filtro, devi leggere il valore dell'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 spiega come configurare i suggerimenti su due diversi widget di immissione 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 
 *  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 immissione di testo possono avere una funzione di gestore setOnChangeAction() definita che viene eseguita ogni volta che il widget perde il focus. 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. L'handler setOnChangeAction() viene eseguito dopo la selezione di un suggerimento.
  2. Se l'utente preme Invio (o fa in modo che l'input di testo perda il focus) senza modificare il suggerimento selezionato, setOnChangeAction() non si attiva nuovamente.
  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.