Sugestie autouzupełniania w przypadku wprowadzania tekstu

Widżet Wprowadzanie tekstu umożliwia dodatkowi odczytywanie tekstu wpisanego przez użytkowników i reagowanie na niego. Dostępne opcje skonfigurować te widżety, aby wyświetlać użytkownikom automatyczne sugestie dotyczące tekst do wprowadzania danych.

Sugestie mogą pochodzić z podanej przez Ciebie statycznej listy ciągów znaków. Możesz też tworzyć sugestie na podstawie kontekstu, np. tekstu. użytkownik już wpisuje dane w widżecie.

Konfigurowanie sugestii

Skonfigurowanie sugestii dotyczących danych wejściowych wymaga wykonania :

• Aby utworzyć listę sugestii:
  • Utworzenie listy statycznej lub
  • Definiowanie działania za pomocą argumentu funkcję wywołania zwrotnego, która dynamicznie tworzy tę listę na podstawie kontekstu.
• Dołącz listę sugestii lub działanie do widżetu wpisywania tekstu.

Jeśli podasz zarówno statyczną listę sugestii, jak i działanie, funkcja interfejs aplikacji korzysta ze statycznej listy, dopóki użytkownik nie zacznie wpisywać znaków, w którym jest używana funkcja wywołania zwrotnego, a lista statyczna jest ignorowana.

Sugestie statyczne

Aby zaoferować statyczną listę sugestii, musisz tylko:

1. Tworzenie Suggestions obiektu.
2. Dodaj do każdej ze statycznych sugestii za pomocą narzędzia addSuggestion() lub addSuggestions().
3. Załącz Suggestions do widżetu przy użyciu TextInput.setSuggestions().

Sugestie statyczne w interfejsie wyświetlają się w takiej kolejności, w jakiej zostały dodane. Interfejs również automatycznie dopasowuje prefiksy bez rozróżniania wielkości liter i filtruje sugestii podczas wpisywania znaków w widżecie.

Działania związane z sugestiami

Jeśli nie używasz statycznej listy sugestii, musisz zdefiniować działanie aby dynamicznie tworzyć sugestie. Aby to zrobić, wykonaj poniższe kroki:

1. Tworzenie obiektu Action i powiąż ją z funkcją wywołania zwrotnego zdefiniowanych przez reklamodawcę.
2. Wywołaj polecenie TextInput.setSuggestionsAction() widżetu zapewniając jej funkcję Action obiektu.
3. Zaimplementuj funkcję wywołania zwrotnego, aby utworzyć listę sugestii i zwrócić utworzony SuggestionsResponse obiektu.

Interfejs wywołuje funkcję wywołania zwrotnego za każdym razem, gdy użytkownik wpisze znak w polu ale tylko wtedy, gdy użytkownik na chwilę przestanie pisać. funkcja wywołania zwrotnego odbiera obiekt zdarzenia z informacjami o parametrze otwierać widżety karty. Zobacz Obiekty zdarzeń działania .

Funkcja wywołania zwrotnego musi zwracać prawidłową wartość SuggestionsResponse obiekt zawierający listę sugestii do wyświetlenia. Interfejs użytkownika sugestie w kolejności ich dodawania. W przeciwieństwie do list statycznych interfejs nie przeprowadzają automatycznego filtrowania sugestii oddzwonień na podstawie danych użytkownika. dane wejściowe. Jeśli chcesz zastosować takie filtrowanie, musisz odczytać wartość wejściową od obiektu zdarzenia i odfiltrowywać sugestie podczas tworzenia listy.

Przykład

Ten fragment kodu dodatku do Google Workspace pokazuje, jak skonfigurować sugestie na dwóch różnych widżetach wprowadzania tekstu: pierwszy ze statyczną listą, za pomocą funkcji wywołania zwrotnego:

// 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!
 }

Sugestie i OnChangeAction()

Widżety wprowadzania tekstu mogą mieć setOnChangeAction() zdefiniowaną funkcję obsługi, która jest wykonywana, gdy widżet straci zaznaczenie. Jeśli zarówno ten moduł obsługi, jak i sugestie są włączone dla tego samego tekstu, funkcja te reguły definiują zachowanie interakcji z wprowadzaniem tekstu:

1. Po wybraniu sugestii uruchamia się moduł obsługi setOnChangeAction().
2. Jeśli użytkownik naciśnie Enter (lub w inny sposób sprawi, że wpisany tekst nie będzie zaznaczony) bez modyfikacji wybranej sugestii, setOnChangeAction() nie: wyzwalacza ponownie.
3. setOnChangeAction() uruchamia się ponownie, jeśli użytkownik po wybraniu sugestia, zmieni ją tak, aby nie była już zgodna z żadną z sugestii z listy.
4. Jeśli użytkownik nie wybierze sugestii, wyzwala je setOnChangeAction() gdy tekst przestaje być aktywny.