Suggerimenti di completamento automatico per gli input di testo

Il widget Inserimento 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 del testo di input.

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

Configurazione dei suggerimenti

Per configurare i suggerimenti per l'input di testo è necessario eseguire seguenti:

  • Crea un elenco di suggerimenti:
    • Creare un elenco statico e/o
    • La definizione di un'azione con è una funzione di callback che crea elenchi in modo 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, UI dell'applicazione utilizza l'elenco statico finché l'utente non inizia a inserire caratteri, dopo di che 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 una Suggestions .
  2. Aggiungi ogni suggerimento statico utilizzando addSuggestion() o addSuggestions().
  3. Collega Suggestions al widget utilizzando TextInput.setSuggestions().

L'interfaccia utente mostra suggerimenti statici nell'ordine in cui sono stati aggiunti. UI esegue automaticamente la corrispondenza dei prefissi senza distinzione tra maiuscole e minuscole e filtra l'elenco di suggerimenti mentre l'utente digita caratteri nel widget.

Azioni sui suggerimenti

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. Creare un oggetto Action e associarla a una funzione di callback che definisci.
  2. Chiama il pulsante TextInput.setSuggestionsAction() del widget che fornisce la funzione Action .
  3. Implementare la funzione callback per creare l'elenco di suggerimenti e restituire un SuggestionsResponse costruito .

L'interfaccia utente chiama la funzione di callback ogni volta che l'utente digita un carattere nella l'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 sul apri i widget della scheda. Consulta: Oggetti di eventi azione per maggiori dettagli.

La funzione di callback deve restituire un valore SuggestionsResponse contenente l'elenco di suggerimenti da visualizzare. La UI mostra 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'utente di testo. Per applicare questo tipo di filtri, devi leggere il valore dell'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 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 inserimento testo possono avere setOnChangeAction() funzione di gestore 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 altrimenti rende l'input di testo perduto lo stato 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ù ad alcun suggerimento nell'elenco.
  4. Se l'utente non seleziona un suggerimento, viene attivato setOnChangeAction() quando l'input di testo perde lo stato attivo.