Autocomplete-Vorschläge für Texteingaben

Mit dem Widget Texteingabe kann das Add-on von Nutzern bereitgestellten Text lesen und darauf reagieren. Sie können diese Widgets so konfigurieren, dass Nutzern automatische Vorschläge für den Eingabetext angezeigt 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 konfigurieren

Wenn Sie Vorschläge für eine Texteingabe konfigurieren möchten, müssen Sie nur Folgendes tun:

  • Sie haben folgende Möglichkeiten, eine Liste mit Vorschlägen zu erstellen:
    • Statische Liste erstellen und/oder
    • Definieren einer Aktion mit einer Callback-Funktion, die die Liste dynamisch aus dem Kontext erstellt.
  • Hängen Sie die Vorschlagsliste und/oder Aktion an das Texteingabe-Widget an.

Wenn Sie sowohl eine statische Liste von Vorschlägen als auch eine Aktion bereitstellen, verwendet die Anwendungs-UI diese statische Liste, bis der Nutzer beginnt, Zeichen einzugeben. In diesem Fall wird die Callback-Funktion verwendet und die statische Liste ignoriert.

Statische Vorschläge

Um eine statische Liste mit Vorschlägen anzubieten, 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 außerdem automatisch einen Präfixabgleich durch, bei dem die Groß-/Kleinschreibung nicht berücksichtigt wird, und filtert die Vorschlagsliste, 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 stellen Sie dafür das Objekt Action bereit.
  3. Implementieren Sie die Callback-Funktion, um die Vorschlagsliste zu erstellen und ein erstelltes SuggestionsResponse-Objekt zurückzugeben.

Die UI ruft die Callback-Funktion immer dann auf, wenn der Nutzer ein Zeichen in die Texteingabe eingibt, jedoch erst, wenn der Nutzer für einen Moment mit der Eingabe aufgehört hat. Die Callback-Funktion empfängt ein Ereignisobjekt, das Informationen zu den Widgets der geöffneten Karte enthält. 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. Die Vorschläge werden in der Reihenfolge angezeigt, in der sie hinzugefügt wurden. Im Gegensatz zu statischen Listen führt die UI keine automatische Filterung von Callback-Vorschlägen anhand der Nutzereingabe durch. Wenn Sie eine solche Filterung nutzen möchten, müssen Sie den Texteingabewert aus dem Ereignisobjekt lesen und Ihre Vorschläge beim Erstellen der Liste filtern.

Beispiel

Das folgende Code-Snippet für das Google Workspace-Add-on zeigt, wie Vorschläge in zwei verschiedenen Texteingabe-Widgets konfiguriert werden, das erste mit einer statischen Liste und das zweite mit 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, definieren die folgenden Regeln das Interaktionsverhalten der Texteingabe:

  1. Der Handler setOnChangeAction() wird ausgeführt, nachdem ein Vorschlag ausgewählt wurde.
  2. Wenn der Nutzer die Eingabetaste drückt oder die Texteingabe aus einem anderen Grund den Fokus 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.