Sugestie autouzupełniania w przypadku wprowadzania tekstu

Widżet Wprowadzanie tekstu umożliwia dodatkowi odczytywanie tekstu przesyłanego przez użytkowników i reagowanie na niego. Możesz skonfigurować te widżety, aby dostarczać użytkownikom automatyczne sugestie dotyczące tekstu wpisywanego.

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

Konfigurowanie sugestii

Aby skonfigurować sugestie dotyczące danych wejściowych:

• Aby utworzyć listę sugestii:
  • Utworzenie listy statycznej lub
  • Zdefiniowanie działania za pomocą funkcji 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, interfejs aplikacji będzie używać listy statycznej, dopóki użytkownik nie zacznie wpisywać znaków. Wtedy funkcja wywołania zwrotnego zostanie użyta, a lista statyczna zostanie zignorowana.

Sugestie statyczne

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

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

Sugestie statyczne w interfejsie wyświetlają się w takiej kolejności, w jakiej zostały dodane. Interfejs automatycznie wyszukuje prefiksy bez rozróżniania wielkości liter i filtruje listę sugestii, gdy użytkownik wpisuje znaki 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. 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ć utworzony obiekt SuggestionsResponse.

Interfejs wywołuje funkcję wywołania zwrotnego za każdym razem, gdy użytkownik wpisze znak w polu tekstowym, ale tylko wtedy, gdy na chwilę przestanie pisać. Funkcja wywołania zwrotnego odbiera obiekt zdarzenia z informacjami o widżetach otwartej karty. Więcej informacji znajdziesz w sekcji Obiekty zdarzeń działań.

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 przeprowadza automatycznego filtrowania sugestii wywołań zwrotnych na podstawie danych wejściowych użytkownika. Jeśli chcesz stosować takie filtrowanie, musisz odczytać wpisaną wartość tekstową z obiektu zdarzenia i przefiltrować sugestie podczas tworzenia listy.

Przykład

Ten fragment kodu dodatku do Google Workspace pokazuje, jak skonfigurować sugestie w 2 różnych widżetach wprowadzania tekstu. Pierwszy zawiera statyczną listę, a drugi funkcję 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ć zdefiniowaną funkcję obsługi setOnChangeAction(), która uruchamia się, gdy widżet przestanie być aktywny. Jeśli zarówno ten moduł obsługi, jak i sugestie są włączone w przypadku tego samego tekstu, te reguły określają sposób interakcji z tym samym tekstem:

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 przestanie być aktywny) bez zmiany wybranej sugestii, funkcja setOnChangeAction() nie uruchomi się ponownie.
3. Reguła setOnChangeAction() zostanie aktywowana ponownie, jeśli użytkownik po wybraniu sugestii zmieni ją w taki sposób, że nie będzie już odpowiadać żadnej z sugestii na liście.
4. Jeśli użytkownik nie wybierze sugestii, setOnChangeAction() aktywuje się, gdy wpisywany tekst przestanie być aktywny.