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:
- Utwórz obiekt
Suggestions
. - Dodaj do nich każdą statyczną sugestię za pomocą metody
addSuggestion()
lubaddSuggestions()
. - Dołącz obiekt
Suggestions
do widżetu za pomocą narzędziaTextInput.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:
- Utwórz obiekt
Action
i powiąż go ze zdefiniowaną przez siebie funkcją wywołania zwrotnego. - Wywołaj funkcję
TextInput.setSuggestionsAction()
widżetu, podając obiektAction
. - 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:
- Po wybraniu sugestii uruchamia się moduł obsługi
setOnChangeAction()
. - 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. - 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. - Jeśli użytkownik nie wybierze sugestii,
setOnChangeAction()
aktywuje się, gdy wpisywany tekst przestanie być aktywny.