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

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

Die Vorschläge können aus einer von Ihnen bereitgestellten statischen Liste von Strings stammen. 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

So konfigurieren Sie Vorschläge für eine Texteingabe:

  • So erstellen Sie eine Liste mit Vorschlägen:
    • Erstellen einer statischen Liste und/oder
    • Definieren Sie eine Aktion mit einer Callback-Funktion, die diese Liste dynamisch aus dem Kontext erstellt.
  • Hängen Sie die Vorschlagsliste und/oder Aktion an das Widget für die Texteingabe 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 Rückruffunktion verwendet und die statische Liste wird ignoriert.

Statische Vorschläge

So bieten Sie eine statische Liste von Vorschlägen an:

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

Die statischen Vorschläge werden in der Benutzeroberfläche in der Reihenfolge angezeigt, in der sie hinzugefügt wurden. Die Benutzeroberfläche führt außerdem automatisch eine zeicheninsensitive Präfixabgleich durch und filtert die Vorschlagsliste, während der Nutzer Zeichen in das Widget eingibt.

Vorschläge für Aktionen

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. Erstelle ein Action-Objekt und verknüpfe es mit einer von dir definierten Callback-Funktion.
  2. Rufen Sie die Funktion TextInput.setSuggestionsAction() des Widgets auf und übergeben Sie das Action-Objekt.
  3. Implementiere die Rückruffunktion, um die Vorschlagsliste zu erstellen und ein erstelltes SuggestionsResponse-Objekt zurückzugeben.

Die Benutzeroberfläche ruft die Rückruffunktion immer dann auf, wenn der Nutzer ein Zeichen in die Texteingabe eingibt, aber erst, nachdem er einen Moment lang nicht mehr getippt hat. Die Rückruffunktion erhält ein Ereignisobjekt mit Informationen zu den Widgets der geöffneten Karte. Weitere Informationen finden Sie unter Ereignisobjekte vom Typ „Aktion“.

Die Callback-Funktion muss ein gültiges SuggestionsResponse-Objekt mit der Liste der anzuzeigenden Vorschläge zurückgeben. Die Vorschläge werden in der Benutzeroberfläche in der Reihenfolge angezeigt, in der sie hinzugefügt wurden. Im Gegensatz zu statischen Listen werden auf der Benutzeroberfläche keine automatischen Filterungen von Rückrufvorschlägen auf Grundlage der Nutzereingabe durchgeführt. Wenn Sie eine solche Filterung verwenden möchten, müssen Sie den Wert der Texteingabe aus dem Ereignisobjekt lesen und die Vorschläge beim Erstellen der Liste filtern.

Beispiel

Im folgenden Code-Snippet für ein Google Workspace-Add-on wird gezeigt, wie Vorschläge in zwei verschiedenen Texteingabe-Widgets konfiguriert werden: das erste mit einer statischen Liste und das zweite mit einer Rückruffunktion:

// 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 
 *  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()-Handlerfunktion definiert werden, die ausgeführt wird, wenn das Widget den Fokus verliert. Wenn dieser Handler und Vorschläge für dieselbe Texteingabe aktiviert sind, definieren die folgenden Regeln das Interaktionsverhalten der Texteingabe:

  1. Der setOnChangeAction()-Handler wird ausgeführt, nachdem ein Vorschlag ausgewählt wurde.
  2. Wenn der Nutzer die Eingabetaste drückt (oder anderweitig den Fokus von der Texteingabe nimmt), 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 so bearbeitet, dass er nicht mehr mit einem der Vorschläge in der Liste übereinstimmt.
  4. Wenn der Nutzer keinen Vorschlag auswählt, wird setOnChangeAction() ausgelöst, wenn der Fokus nicht mehr auf der Texteingabe liegt.