Vorschläge der automatischen Vervollständigung für Texteingaben

Widget Texteingabe kann das Add-on Text von Nutzern lesen und darauf reagieren. Sie können diese Widgets so konfigurieren, dass Nutzern automatische Vorschläge für Text ein.

Die Vorschläge können aus einer statischen Liste von Strings stammen, die Sie angeben. Alternativ können Sie die Vorschläge aus dem Kontext erstellen, z. B. aus dem Text die der Nutzer bereits in das Widget eingegeben hat.

Vorschläge werden konfiguriert

Zum Konfigurieren von Vorschlägen für eine Texteingabe müssen Sie nur Folgendes tun: Folgendes:

  • So erstellen Sie eine Liste mit Vorschlägen:
    • Erstellen einer statischen Liste und/oder
    • Definieren einer Aktion mit eine Callback-Funktion, die diese Liste dynamisch aus dem Kontext erstellt.
  • Hängen Sie die Vorschlagsliste und/oder die Aktion an das Texteingabe-Widget an.

Wenn Sie sowohl eine statische Liste mit Vorschlägen als auch eine Aktion bereitstellen, die statische Liste verwendet, bis der Nutzer beginnt, Zeichen einzugeben, wobei die Callback-Funktion verwendet und die statische Liste ignoriert wird.

Statische Vorschläge

Wenn Sie eine statische Liste von Vorschlägen bereitstellen möchten, müssen Sie nur Folgendes tun:

  1. Suggestions erstellen -Objekt enthält.
  2. Fügen Sie jeden statischen Vorschlag mit addSuggestion() hinzu oder addSuggestions().
  3. Hängen Sie den Suggestions an. mithilfe von TextInput.setSuggestions() ein Objekt an das Widget senden.

Die Benutzeroberfläche zeigt statische Vorschläge in der Reihenfolge an, in der sie hinzugefügt wurden. Die Benutzeroberfläche führt automatisch einen Präfixabgleich zwischen Groß- und Kleinschreibung durch und filtert während der Nutzer Zeichen in das Widget eingibt.

Vorschlagsaktionen

Wenn Sie keine statische Vorschlagsliste verwenden, müssen Sie eine Aktion definieren um Ihre Vorschläge dynamisch zu erstellen. Gehe dazu wie folgt vor:

  1. Action-Objekt erstellen und mit einer Callback-Funktion verknüpfen, die Sie definieren.
  2. Rufen Sie die Methode TextInput.setSuggestionsAction() des Widgets auf. und geben dabei den Action an. -Objekt enthält.
  3. Implementieren Sie die Callback-Funktion, um die Vorschlagsliste zu erstellen und zurückzugeben, ein erstelltes SuggestionsResponse -Objekt enthält.

Über die Benutzeroberfläche wird immer dann die Callback-Funktion aufgerufen, wenn der Nutzer ein Zeichen in die Texteingabe beginnen, aber erst, nachdem der Nutzer die Eingabe für einen Moment beendet hat. Die Callback-Funktion ein Ereignisobjekt mit Informationen zum um die Widgets der Karte zu öffnen. Weitere Informationen finden Sie unter Aktionsereignisobjekte .

Die Callback-Funktion muss eine gültige SuggestionsResponse Objekt, das die Liste der anzuzeigenden Vorschläge enthält. Die Benutzeroberfläche wird in der Reihenfolge an, in der sie hinzugefügt wurden. Im Gegensatz zu statischen Listen hat die Benutzeroberfläche keine automatische Filterung von Callback-Vorschlägen nach Nutzer- Eingabe. Wenn Sie eine solche Filterung verwenden möchten, müssen Sie den Texteingabewert lesen aus dem Ereignisobjekt und filtern Sie beim Erstellen der Liste die Vorschläge.

Beispiel

Das folgende Code-Snippet für das Google Workspace-Add-on zeigt, wie Vorschläge konfiguriert werden auf zwei verschiedenen Texteingabe-Widgets, das erste mit einer statischen Liste und dem mithilfe einer Callback-Funktion:

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

Vorschläge und OnChangeAction()

Texteingabe-Widgets können eine setOnChangeAction() Definierte Handler-Funktion, die ausgeführt wird, wenn das Widget den Fokus verliert. Wenn sowohl dieser Handler als auch Vorschläge für dieselbe Texteingabe aktiviert sind, Folgende Regeln definieren das Interaktionsverhalten bei der Texteingabe:

  1. Der Handler setOnChangeAction() wird ausgeführt, nachdem ein Vorschlag ausgewählt wurde.
  2. Wenn die nutzende Person die Eingabetaste drückt (oder die Texteingabe aus anderen Gründen verliert) ohne den ausgewählten Vorschlag zu ändern, tut setOnChangeAction() dies nicht noch einmal auslösen.
  3. setOnChangeAction() wird noch einmal ausgelöst, wenn der Nutzer nach Auswahl eines bearbeitet, sodass er keinem der Vorschläge mehr entspricht. in der Liste.
  4. Wenn der Nutzer keinen Vorschlag auswählt, wird setOnChangeAction() ausgelöst wenn die Texteingabe den Fokus verliert.