Działania dodatku zapewniają interaktywność widżetów. Tworząc działanie, określasz, co ma się dziać, gdy użytkownik wybierze lub zaktualizuje widżet.
W większości przypadków możesz zdefiniować działania dodatku za pomocą obiektów Action udostępnianych przez usługę kart w Apps Script.
Każdy element Action jest powiązany z funkcją wywołania zwrotnego, gdy go tworzysz. Funkcję wywołania zwrotnego implementujesz, aby wykonać określone czynności, gdy użytkownik będzie wchodzić w interakcję z widżetem. Musisz też połączyć Action z widżetem za pomocą odpowiedniej funkcji obsługi widżetu, która określa, jaki rodzaj interakcji powoduje wywołanie Action.
Aby skonfigurować widżet z użyciem Action:
- Utwórz obiekt
Action, podając funkcję wywołania zwrotnego, którą ma wykonać, wraz z wymaganymi parametrami. - Wywołaj odpowiednią funkcję obsługi widżetu na widżecie za pomocą obiektu
Action. - Zaimplementuj funkcję wywołania zwrotnego, aby uzyskać wymagane działanie.
Funkcje obsługi widżetu
Aby powiązać widżet z określonym Actionlub innym działaniem, użyj funkcji obsługi widżetu. Funkcja obsługi określa, jaka interakcja (np. kliknięcie widżetu lub edytowanie pola tekstowego) powoduje działanie. Funkcja obsługi określa też, jakie kroki interfejs użytkownika wykonuje po zakończeniu działania.
W tabeli poniżej znajdziesz listę różnych typów obsługi widgetów i ich zastosowanie:
| Funkcja obsługi | Działanie aktywatora | Odpowiednie widżety | Opis |
|---|---|---|---|
setOnChangeAction() |
wartość widżetu ulega zmianie. |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Ustawia element Action, który wykonuje funkcję Apps Script, gdy widget traci fokus, na przykład gdy użytkownik wpisze tekst w polu tekstowym i naciśnie klawisz Enter. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej przez niego funkcji.
W razie potrzeby możesz w tym obiekcie zdarzenia wstawić dodatkowe informacje o parametrach. |
setOnClickAction() |
Użytkownik klika widżet |
CardActionImageImageButtonDecoratedTextTextButton
|
Ustawia Action, który wykonuje funkcję Apps Script, gdy użytkownik kliknie widget. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej przez niego funkcji.
W tym obiekcie zdarzenia możesz wstawić opcjonalne informacje o parametrach. |
setComposeAction() |
Użytkownik klika widżet |
CardActionImageImageButtonDecoratedTextTextButton
|
W przypadku Gmaila Ustawia Action, który tworzy wersję roboczą e-maila, a następnie przedstawia ją użytkownikowi w oknie tworzenia wiadomości w Gmailu. Możesz utworzyć wersję roboczą jako nową wiadomość lub odpowiedź na otwartą wiadomość w Gmailu. Gdy funkcja obsługi wywołuje funkcję wywołania zwrotnego służącą do tworzenia wersji roboczej, przekazuje do niej obiekt zdarzenia.
Więcej informacji znajdziesz w sekcji Tworzenie wersji roboczych wiadomości. |
setOnClickOpenLinkAction() |
Użytkownik klika widżet |
CardActionImageImageButtonDecoratedTextTextButton
|
Ustawia wartość Action
do otwierania adresu URL po kliknięciu widżetu przez użytkownika. Używaj tego modułu obsługi, gdy przed otwarciem linku musisz utworzyć adres URL lub wykonać inne czynności. W innych przypadkach łatwiej jest użyć modułu setOpenLink().
Adres URL można otworzyć tylko w nowym oknie. Gdy jest zamknięty, możesz spowodować, że interfejs użytkownika ponownie wczyta dodatek. |
setOpenLink() |
Użytkownik klika widżet |
CardActionImageImageButtonDecoratedTextTextButton
|
Gdy użytkownik kliknie widżet, otwiera się bezpośrednio adres URL. Używaj tego
handlera, gdy znasz adres URL i chcesz go tylko otworzyć; w przeciwnym razie użyj
setOnClickOpenLinkAction().
Adres URL możesz otworzyć w nowym oknie lub w przeźroczystym oknie. Gdy jest zamknięty, możesz spowodować, że interfejs ponownie wczyta dodatek. |
setSuggestionsAction() |
Użytkownik wpisze tekst w polu tekstowym. |
TextInput
|
Ustawia Action, który wykonuje funkcję Apps Script, gdy użytkownik wpisze tekst w widżecie do wprowadzania tekstu. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej przez niego funkcji.
Więcej informacji znajdziesz w artykule Autouzupełnianie sugestii dla pól tekstowych. |
Funkcje wywołania zwrotnego
Funkcje wywołania zwrotnego są wykonywane po wywołaniu zdarzenia Action. Funkcja wywołania zwrotnego jest funkcją Apps Script, więc może wykonywać niemal wszystkie czynności, które może wykonać dowolna inna funkcja skryptu.
Funkcja wywołania zwrotnego czasami zwraca określony obiekt odpowiedzi. Te typy odpowiedzi wskazują dodatkowe operacje, które muszą zostać wykonane po zakończeniu wykonywania funkcji wywołania zwrotnego, np. wyświetlenie nowej karty lub przedstawienie sugestii autouzupełniania. Jeśli funkcja wywołania zwrotnego musi zwracać określony obiekt odpowiedzi, do jego utworzenia używasz klasy konstruktora w usłudze kart.
Tabela poniżej pokazuje, kiedy funkcje wywołania zwrotnego muszą zwracać określony obiekt odpowiedzi w przypadku określonych działań. Wszystkie te działania są niezależne od konkretnej aplikacji hosta, którą rozszerza dodatek:
| Podejmowane działanie | Wywołanie zwrotne powinno zwrócić |
|---|---|
| Przechodzenie między kartami | ActionResponse |
Wyświetlanie Notification |
ActionResponse |
Otwieranie linku za pomocą setOnClickOpenLinkAction() |
ActionResponse |
| Wyświetlanie sugestii autouzupełniania | SuggestionResponse |
| Użyj działania uniwersalnego. | UniversalActionResponse |
| Inne czynności | Nothing |
Oprócz tych działań każda aplikacja hosta ma własny zestaw działań, które można wykonać tylko w tym hostie. Szczegółowe informacje znajdziesz w tych przewodnikach:
Obiekty zdarzeń akcji
Gdy dodatek uruchamia zdarzenie Action, interfejs użytkownika automatycznie tworzy obiekt zdarzenia JSON i przekazuje go jako argument do funkcji wywołania zwrotnego Action. Ten obiekt zdarzenia zawiera informacje o bieżącym kontekście po stronie klienta użytkownika, np. bieżące wartości wszystkich interaktywnych widgetów na wyświetlonej karcie.
Obiekty zdarzeń akcji mają określoną strukturę JSON, która porządkuje zawarte w nich informacje. Ta sama struktura jest używana, gdy reguła strony głównej uruchamia tworzenie strony głównej lub gdy reguła kontekstowa uruchamia aktualizację wyświetlania dodatku.
Pełne wyjaśnienie struktury obiektu zdarzenia znajdziesz w sekcji Obiekty zdarzenia.