Sugestie autouzupełniania w przypadku wprowadzania tekstu

Widżet Wprowadzanie tekstu umożliwia odczytywanie tekstu podanego przez użytkowników i reagowanie na niego. Możesz skonfigurować te widżety, aby automatycznie sugerować użytkownikom tekst do wpisania.

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

Konfigurowanie sugestii

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

• Utwórz listę sugestii, wykonując te czynności:
  • tworzenie 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 aplikacji będzie używać statycznej listy, dopóki użytkownik nie zacznie wpisywać znaków. Wtedy zostanie użyta funkcja wywołania zwrotnego, a statyczna lista zostanie zignorowana.

Sugestie statyczne

Aby oferować statyczną listę sugestii, wystarczy wykonać te czynności:

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

Interfejs wyświetla statyczne sugestie w kolejności, w jakiej zostały dodane. Interfejs automatycznie wykonuje też dopasowywanie prefiksów bez uwzględniania wielkości liter i filtruje listę sugestii podczas wpisywania znaków w widżecie.

Sugerowane działania

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, przekazując jej 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 otrzymuje obiekt zdarzenia zawierający informacje o widżetach otwartej karty. Szczegółowe informacje 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, w jakiej zostały dodane. W przeciwieństwie do list statycznych interfejs nie przeprowadza automatycznego filtrowania sugestii wywołań zwrotnych na podstawie danych wejściowych użytkownika. Jeśli chcesz zastosować takie filtrowanie, musisz odczytać wartość wprowadzoną w polu tekstowym z obiektu zdarzenia i filtrować sugestie podczas tworzenia listy.

Przykład

Ten fragment kodu dodatku Google Workspace pokazuje, jak skonfigurować sugestie w 2 różnych widżetach wprowadzania tekstu. Pierwszy z nich korzysta ze statycznej listy, a drugi z 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ć zdefiniowaną funkcję obsługi setOnChangeAction(), która jest wykonywana, gdy widżet traci fokus. Jeśli ten moduł obsługi i sugestie są włączone w przypadku tego samego pola tekstowego, zachowanie interakcji z polem tekstowym jest określane przez te reguły:

1. Procedura obsługi setOnChangeAction() jest wykonywana po wybraniu sugestii.
2. Jeśli użytkownik naciśnie Enter (lub w inny sposób spowoduje utratę fokusu przez pole tekstowe) bez modyfikowania wybranej sugestii, funkcja setOnChangeAction() nie zostanie ponownie wywołana.
3. setOnChangeAction() zostanie ponownie wywołane, jeśli użytkownik po wybraniu sugestii zmodyfikuje ją tak, że nie będzie już pasować do żadnej z sugestii na liście.
4. Jeśli użytkownik nie wybierze sugestii, setOnChangeAction() zostanie wywołany, gdy pole tekstowe straci fokus.