Sugestie autouzupełniania w przypadku wprowadzania tekstu

Widget Tekst umożliwia dodatkowi odczytywanie tekstu podanego przez użytkowników i reagowanie na niego. Możesz skonfigurować te widżety, aby wyświetlać użytkownikom automatyczne sugestie dotyczące wprowadzanego tekstu.

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

Konfigurowanie sugestii

Aby skonfigurować sugestie dla pola tekstowego, musisz wykonać te czynności:

• Aby utworzyć listę sugestii:
  • tworzenie listy statycznej lub
  • Zdefiniuj działanie za pomocą funkcji wywołania zwrotnego, która tworzy tę listę dynamicznie na podstawie kontekstu.
• Dodaj listę sugestii lub działanie do widżetu wprowadzania tekstu.

Jeśli podasz stałą listę sugestii i działanie, interfejs użytkownika aplikacji będzie używać listy statycznej, dopóki użytkownik nie zacznie wpisywać znaków. Wtedy zostanie użyta funkcja wywołania zwrotnego, a lista statyczna zostanie zignorowana.

Statyczne sugestie

Aby zaoferować stałą listę sugestii:

1. Utwórz obiekt Suggestions.
2. Dodaj do niego każdą stałą sugestię, używając addSuggestion() lub addSuggestions().
3. Za pomocą TextInput.setSuggestions() dołącz obiekt Suggestions do widżetu.

Interfejs użytkownika wyświetla sugestie statyczne w kolejności, w jakiej zostały dodane. Interfejs automatycznie dopasowuje prefiksy bez uwzględniania wielkości liter i filtruje listę sugestii, gdy użytkownik wpisze znaki w widżecie.

Sugerowane działania

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

1. Utwórz obiekt Action i połącz go ze zdefiniowaną przez siebie funkcją wywołania zwrotnego.
2. Wywołaj funkcję TextInput.setSuggestionsAction() widgeta, przekazując jej obiekt Action.
3. Zaimplementuj funkcję wywołania zwrotnego, aby utworzyć listę sugestii, i zwróć utworzony obiekt SuggestionsResponse.

Interfejs wywołuje funkcję wywołania zwrotnego za każdym razem, gdy użytkownik wpisze znak w polu tekstowym, ale tylko po tym, jak przestanie na chwilę pisać. Funkcja wywołania zwraca 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. Interfejs wyświetla sugestie w kolejności ich dodawania. W przeciwieństwie do list statycznych interfejs użytkownika nie filtruje automatycznie sugestii połączeń zwrotnych na podstawie danych wejściowych użytkownika. Jeśli chcesz stosować takie filtrowanie, musisz odczytać wartość tekstu z obiektu zdarzenia i podczas tworzenia listy odfiltrowywać sugestie.

Przykład

Ten fragment kodu dodatku Google Workspace pokazuje, jak skonfigurować sugestie w 2 różnych widżetach wprowadzania tekstu: pierwszy z listą statyczną, a drugi z 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()

W przypadku widżetów z polem tekstowym można zdefiniować funkcję obsługi setOnChangeAction(), która jest wykonywana, gdy wskaźnik kursora opuszcza widżet. Jeśli ten moduł obsługi i sugestie są włączone w przypadku tego samego pola tekstowego, interakcja z polem tekstowym jest określana przez te reguły:

1. Po wybraniu sugestii wykonywany jest moduł obsługi setOnChangeAction().
2. Jeśli użytkownik naciśnie klawisz Enter (lub w inny sposób spowoduje utratę fokusu przez pole tekstowe) bez modyfikowania wybranej sugestii, setOnChangeAction() nie zostanie ponownie wywołana.
3. setOnChangeAction() uruchamia się ponownie, jeśli użytkownik po wybraniu sugestii zmieni ją tak, aby nie pasowała już do żadnej z sugestii na liście.
4. Jeśli użytkownik nie wybierze sugestii, setOnChangeAction() zostanie wywołane, gdy pole tekstowe utraci fokus.