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

Mit dem Widget Texteingabe kann das Add-on Text lesen und darauf reagieren. Diese Widgets lassen sich so konfigurieren, dass Nutzern automatische Vorschläge für Texteingabe vorgeschlagen werden.

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, den 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:

  • So erstellen Sie eine Liste mit Vorschlägen:
    • Erstellen einer statischen Liste und/oder
    • Eine Aktion mit einer Callback-Funktion definieren, 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, verwendet die Anwendungs-UI die statische Liste, bis der Nutzer beginnt, Zeichen einzugeben. Anschließend wird die Callback-Funktion verwendet und die statische Liste ignoriert.

Statische Vorschläge

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

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

Die Benutzeroberfläche zeigt statische Vorschläge in der Reihenfolge an, in der sie hinzugefügt wurden. Die UI führt auch automatisch einen Präfixabgleich zwischen Groß- und Kleinschreibung durch und filtert die Vorschlagsliste heraus, 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. Erstellen Sie ein Action-Objekt und verknüpfen Sie es mit einer von Ihnen definierten Callback-Funktion.
  2. Rufen Sie die Funktion TextInput.setSuggestionsAction() des Widgets auf und geben Sie dabei das Objekt Action an.
  3. Implementieren Sie die Callback-Funktion, um die Vorschlagsliste zu erstellen und ein erstelltes SuggestionsResponse-Objekt zurückzugeben.

Die UI ruft die Callback-Funktion auf, wenn der Nutzer ein Zeichen in die Texteingabe eingibt, aber erst, nachdem der Nutzer die Eingabe für einen Moment beendet hat. Die Callback-Funktion empfängt ein Ereignisobjekt mit Informationen zu den Widgets der geöffneten Karte. Weitere Informationen finden Sie unter Aktionsereignisobjekte.

Die Callback-Funktion muss ein gültiges SuggestionsResponse-Objekt zurückgeben, das die Liste der anzuzeigenden Vorschläge enthält. In der UI werden Vorschläge in der Reihenfolge angezeigt, in der sie hinzugefügt wurden. Im Gegensatz zu statischen Listen werden in der UI keine Callback-Vorschläge basierend auf der Nutzereingabe automatisch gefiltert. Wenn Sie eine solche Filterung nutzen möchten, müssen Sie den Texteingabewert aus dem Ereignisobjekt auslesen und die Vorschläge beim Erstellen der Liste filtern.

Beispiel

Das folgende Code-Snippet für das Google Workspace-Add-on zeigt, wie Vorschläge für zwei verschiedene Texteingabe-Widgets konfiguriert werden: das erste mit einer statischen Liste und das zweite 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()

Für Texteingabe-Widgets kann eine setOnChangeAction()-Handler-Funktion definiert sein, die ausgeführt wird, wenn das Widget den Fokus verliert. Wenn sowohl dieser Handler als auch Vorschläge für dieselbe Texteingabe aktiviert sind, wird das Interaktionsverhalten bei der Texteingabe durch die folgenden Regeln definiert:

  1. Der Handler setOnChangeAction() wird ausgeführt, nachdem ein Vorschlag ausgewählt wurde.
  2. Wenn der Nutzer die Eingabetaste drückt oder den Fokus auf die Texteingabe verliert, ohne den ausgewählten Vorschlag zu ändern, wird setOnChangeAction() nicht noch einmal ausgelöst.
  3. setOnChangeAction() wird noch einmal ausgelöst, wenn der Nutzer einen Vorschlag nach der Auswahl so bearbeitet, dass er mit keinem der Vorschläge in der Liste mehr übereinstimmt.
  4. Wenn der Nutzer keinen Vorschlag auswählt, wird setOnChangeAction() ausgelöst, wenn die Texteingabe nicht mehr im Fokus ist.