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

Mit dem Widget Texteingabe kann Ihr Add-on Text lesen und darauf reagieren, den Nutzer eingeben. Sie können diese Widgets so konfigurieren, dass Nutzer automatisch Vorschläge für Eingabetext erhalten.

Die Vorschläge können aus einer statischen Liste von Strings stammen, die Sie bereitstellen. 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

Um Vorschläge für eine Texteingabe zu konfigurieren, müssen Sie nur Folgendes tun:

  • So erstellen Sie eine Liste mit Vorschlägen:
    • Erstellen einer statischen Liste und/oder
    • Definieren Sie eine Aktion mit einer Callback-Funktion, die die 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 angeben, wird in der Benutzeroberfläche der Anwendung die statische Liste verwendet, bis der Nutzer Zeichen eingibt. Dann wird die Callback-Funktion verwendet und die statische Liste wird ignoriert.

Statische Vorschläge

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

  1. Erstellen Sie ein Suggestions-Objekt.
  2. Fügen Sie jede statische Empfehlung mit addSuggestion() oder addSuggestions() hinzu.
  3. Hängen Sie das Suggestions-Objekt mit TextInput.setSuggestions() an das Widget an.

In der Benutzeroberfläche werden statische Vorschläge in der Reihenfolge angezeigt, in der sie hinzugefügt wurden. Die Benutzeroberfläche führt außerdem automatisch eine nicht berücksichtigende Präfixübereinstimmung durch 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 Callback-Funktion, die Sie definieren.
  2. Rufen Sie die Funktion TextInput.setSuggestionsAction() des Widgets auf und übergeben Sie das Objekt Action.
  3. Implementieren Sie die Callback-Funktion, um die Vorschlagsliste zu erstellen und ein erstelltes SuggestionsResponse-Objekt zurückzugeben.

Die Callback-Funktion wird von der Benutzeroberfläche aufgerufen, wenn der Nutzer ein Zeichen in das Textfeld eingibt, aber erst, nachdem der Nutzer eine Weile nicht mehr getippt 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 mit der Liste der anzuzeigenden Vorschläge zurückgeben. In der Benutzeroberfläche werden Vorschläge in der Reihenfolge angezeigt, in der sie hinzugefügt werden. Im Gegensatz zu statischen Listen werden in der Benutzeroberfläche keine automatischen Filter für Rückrufvorschläge auf Grundlage der Nutzereingabe angewendet. Wenn Sie eine solche Filterung wünschen, müssen Sie den Texteingabewert aus dem Ereignisobjekt lesen und Ihre Vorschläge beim Erstellen der Liste filtern.

Beispiel

Das folgende Google Workspace-Add-on-Code-Snippet zeigt, wie Vorschläge für zwei verschiedene Text-Eingabe-Widgets konfiguriert werden. Das erste verwendet eine statische Liste, das zweite eine 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 Text-Eingabe-Widgets kann eine setOnChangeAction()-Handler-Funktion definiert werden, die immer dann ausgeführt wird, wenn das Widget den Fokus verliert. Wenn dieser Handler und Vorschläge für dieselbe Texteingabe aktiviert sind, gelten die folgenden Regeln für das Interaktionsverhalten bei der Texteingabe:

  1. Der setOnChangeAction()-Handler wird ausgeführt, nachdem ein Vorschlag ausgewählt wurde.
  2. Wenn der Nutzer die Eingabetaste drückt (oder die Texteingabe auf andere Weise 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 auswählt und ihn dann 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 der Fokus aus der Texteingabe entfernt wird.