Sugestie autouzupełniania w przypadku wprowadzania tekstu

Widżet Tekst do wprowadzania tekstu umożliwia dodatkowi odczytywanie tekstu podawanego przez użytkowników i reagowanie na nie. Możesz skonfigurować te widżety, aby automatycznie wyświetlać użytkownikom automatyczne sugestie dotyczące tekstu wejściowego.

Sugestie mogą pochodzić ze statycznej listy ciągów tekstowych. Sugestie możesz też tworzyć na podstawie kontekstu, np. tekstu, który użytkownik już wpisał w widżecie.

Konfigurowanie sugestii

Aby skonfigurować sugestie dotyczące wprowadzania tekstu, musisz tylko wykonać te czynności:

• Utwórz listę sugestii według:
  • utworzenia listy statycznej lub
  • Zdefiniowanie działania za pomocą funkcji wywołania zwrotnego, która dynamicznie tworzy listę na podstawie kontekstu.
• Dołącz listę sugestii lub działanie do widżetu wprowadzania tekstu.

Jeśli podasz zarówno statyczną listę sugestii, jak i działanie, interfejs użytkownika aplikacji będzie używał listy statycznej do czasu, aż użytkownik zacznie wpisywać znaki, po czym zostanie użyta funkcja wywołania zwrotnego, a lista statyczna jest ignorowana.

Sugestie statyczne

Aby zaoferować statyczną listę sugestii:

1. Utwórz obiekt Suggestions.
2. Dodaj do niej każdą statyczną sugestię za pomocą funkcji addSuggestion() lub addSuggestions().
3. Dołącz obiekt Suggestions do widżetu za pomocą TextInput.setSuggestions().

Interfejs wyświetla statyczne sugestie w kolejności, w jakiej zostały dodane. Interfejs użytkownika automatycznie przeprowadza też dopasowywanie prefiksów bez rozróżniania wielkości liter i filtruje listę sugestii, gdy użytkownik wpisuje znaki w widżecie.

Działania dotyczące sugestii

Jeśli nie używasz statycznej listy sugestii, musisz zdefiniować działanie w celu dynamicznego tworzenia sugestii. Aby to zrobić, wykonaj poniższe kroki:

1. Utwórz obiekt Action i powiąż go ze zdefiniowaną przez siebie funkcją wywołania zwrotnego.
2. Wywołaj funkcję TextInput.setSuggestionsAction() widżetu, podając obiekt Action.
3. Zaimplementuj funkcję wywołania zwrotnego, aby utworzyć listę sugestii i zwrócić skompilowany obiekt SuggestionsResponse.

Interfejs użytkownika wywołuje funkcję wywołania zwrotnego za każdym razem, gdy użytkownik wpisze znak w tekście, ale tylko wtedy, gdy na chwilę przestanie pisać. Funkcja wywołania zwrotnego otrzymuje obiekt zdarzenia zawierający informacje o widżetach otwartej karty. Więcej informacji znajdziesz w sekcji Obiekty zdarzeń działania.

Funkcja wywołania zwrotnego musi zwracać prawidłowy obiekt SuggestionsResponse zawierający listę sugestii do wyświetlenia. Sugestie wyświetlają się w kolejności ich dodawania. W przeciwieństwie do list statycznych interfejs użytkownika nie filtruje automatycznie sugestii wywołań zwrotnych na podstawie danych wejściowych użytkownika. Jeśli chcesz skorzystać z takiego filtrowania, musisz odczytać wartość wejściową z obiektu zdarzenia i odfiltrować sugestie podczas tworzenia listy.

Przykład

Poniższy fragment kodu dodatku do Google Workspace pokazuje, jak skonfigurować sugestie w 2 różnych widżetach do wprowadzania tekstu: pierwszy ma listę statyczną, a drugi przy użyciu 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 do wprowadzania tekstu mogą mieć zdefiniowaną funkcję obsługi setOnChangeAction(), która jest uruchamiana, gdy widżet przestaje być aktywny. Jeśli ten moduł obsługi i sugestie są włączone w przypadku tych samych danych wejściowych, interakcje związane z wprowadzaniem tekstu określają te reguły:

1. Moduł obsługi setOnChangeAction() jest wykonywany po wybraniu sugestii.
2. Jeśli użytkownik naciśnie Enter (lub w inny sposób spowoduje utratę zaznaczenia tekstu) bez zmiany wybranej sugestii, właściwość setOnChangeAction() nie zostanie ponownie wywołana.
3. Reguła setOnChangeAction() jest ponownie wywołana, gdy użytkownik po wybraniu sugestii zmieni ją tak, aby nie odpowiadała żadnej sugestii na liście.
4. Jeśli użytkownik nie wybierze sugestii, wywołanie setOnChangeAction() spowoduje, że zaznaczone pole tekstowe przestanie być zaznaczone.