Vorschläge der automatischen Vervollständigung 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 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:

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

Wenn Sie sowohl eine statische Liste von Vorschlägen als auch eine Aktion bereitstellen, verwendet die Anwendungs-UI die statische Liste so lange, bis der Nutzer mit der Eingabe von Zeichen beginnt. Daraufhin wird die Callback-Funktion verwendet und die statische Liste 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 jeden statischen Vorschlag mit addSuggestion() oder addSuggestions() hinzu.
  3. Hängen Sie das Objekt Suggestions mithilfe von TextInput.setSuggestions() an das Widget an.

Auf der Benutzeroberfläche werden statische Vorschläge in der Reihenfolge angezeigt, 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 zum dynamischen Erstellen der Vorschläge definieren. 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 dafür 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 immer dann auf, wenn der Nutzer ein Zeichen in die Texteingabe eingibt, aber erst, wenn der Nutzer die Eingabe kurz unterbrochen 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 Benutzeroberfläche keine automatische Filterung von Callback-Vorschlägen anhand der Nutzereingabe durch. Wenn Sie eine solche Filterung verwenden 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 für zwei verschiedene 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, wird das Interaktionsverhalten der Texteingabe durch die folgenden Regeln definiert:

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