Dodatki umożliwiają interaktywne działanie widżetów. Tworząc działanie, określasz, co ma się stać, gdy użytkownik wybierze lub zaktualizuje widżet.
W większości przypadków możesz zdefiniować dodatkowe działania za pomocą obiektów Action udostępnianych przez usługę karty Apps Script.
Podczas tworzenia każdego obiektu Action jest on powiązany z funkcją wywołania zwrotnego. Wdróż funkcję wywołania zwrotnego, aby wykonywać pożądane działania, gdy użytkownik wejdzie 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 rodzaj interakcji wyzwalającej wywołanie zwrotne Action.
Aby skonfigurować widżet przy użyciu Action, wykonaj te ogólne czynności:
- Utwórz obiekt
Action, określając funkcję wywołania zwrotnego, którą powinna wykonać, oraz wszystkie wymagane parametry. - Wywołaj odpowiednią funkcję obsługi widżetu za pomocą obiektu
Action. - Zaimplementuj funkcję wywołania zwrotnego, aby wywołać wymagane zachowanie.
Funkcje obsługi widżetów
Aby połączyć widżet z konkretnym obiektem Action lub innym działaniem, możesz użyć funkcji obsługi widżetów. Moduł obsługi określa, jaki rodzaj interakcji (np. kliknięcie widżetu czy edycja pola tekstowego) aktywuje dane działanie. Moduł obsługi określa też, jakie działania może wykonać interfejs użytkownika po zakończeniu danego działania.
W tabeli poniżej znajdziesz listę różnych typów modułów obsługi widżetów i widżetów, z którymi są one używane:
| Funkcja obsługi | Działanie aktywujące | Dostępne widżety | Opis |
|---|---|---|---|
setOnChangeAction() |
Wartość widżetu zmienia się |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Ustawia Action, który wykonuje funkcję Apps Script, gdy widżet przestanie być aktywny, na przykład wtedy, gdy użytkownik wpisze wpisany tekst i naciśnie Enter. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej 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 widżet. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej funkcji.
W tym obiekcie zdarzenia możesz wstawić opcjonalne informacje o parametrach. |
setComposeAction() |
Użytkownik klika widżet. |
CardActionImageImageButtonDecoratedTextTextButton
|
Dotyczy tylko Gmaila. Ustawia Action, który tworzy wersję roboczą e-maila, a następnie wyświetla ją użytkownikowi w oknie tworzenia wiadomości w interfejsie Gmaila. Wersję roboczą wiadomości możesz utworzyć jako nową wiadomość lub odpowiedź na otwartą wiadomość w Gmailu. Gdy moduł obsługi wywołuje funkcję wywołania zwrotnego kompilacji wersji roboczej, przekazuje do niej obiekt zdarzenia.
Więcej informacji znajdziesz w artykule Tworzenie wersji roboczych wiadomości. |
setOnClickOpenLinkAction() |
Użytkownik klika widżet. |
CardActionImageImageButtonDecoratedTextTextButton
|
Ustawia Action tak, aby adres URL otwierał się, gdy użytkownik kliknie widżet. Użyj tego modułu obsługi, gdy musisz utworzyć adres URL lub gdy inne działania muszą zostać wykonane przed otwarciem linku. W przeciwnym razie zwykle łatwiej jest użyć obiektu setOpenLink().
Ten adres URL możesz otworzyć tylko w nowym oknie. Po zamknięciu dodatku możesz ponownie załadować dodatek w interfejsie. |
setOpenLink() |
Użytkownik klika widżet. |
CardActionImageImageButtonDecoratedTextTextButton
|
Otwiera bezpośrednio adres URL, gdy użytkownik kliknie widżet. Używaj tego modułu obsługi, gdy znasz adres URL i chcesz tylko go otworzyć. W przeciwnym razie użyj funkcji setOnClickOpenLinkAction().
Możesz otworzyć adres URL w nowym oknie lub w nakładce. Po zamknięciu dodatku możesz ponownie załadować dodatek w interfejsie. |
setSuggestionsAction() |
Użytkownik wpisuje tekst. |
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 funkcji.
Więcej informacji znajdziesz w artykule Sugestie autouzupełniania podczas wpisywania tekstu. |
Funkcje wywołania zwrotnego
Funkcje wywołania zwrotnego są wykonywane po wywołaniu parametru Action. Funkcja wywołania zwrotnego to funkcje Apps Script, więc możesz na nich wykonywać prawie wszystkie inne funkcje skryptu.
Funkcja wywołania zwrotnego czasem zwraca określony obiekt odpowiedzi. Tego typu odpowiedzi wskazują dodatkowe operacje, które muszą zostać wykonane po zakończeniu wywołania zwrotnego, takie jak wyświetlenie nowej karty lub przedstawienie sugestii autouzupełniania. Gdy funkcja wywołania zwrotnego musi zwrócić określony obiekt odpowiedzi, do utworzenia tego obiektu użyj klasy konstruktora w usłudze karty.
W tabeli poniżej pokazujemy, kiedy funkcje wywołania zwrotnego muszą zwracać określony obiekt odpowiedzi dla określonych działań. Wszystkie te działania są niezależne od konkretnej aplikacji hosta rozszerzanego przez dodatek:
| Podjęto próbę wykonania działania | Funkcja wywołania zwrotnego powinna zwrócić |
|---|---|
| poruszać się między kartami; | ActionResponse |
Wyświetl Notification |
ActionResponse |
Otwieranie linku przy użyciu narzędzia 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 hostująca ma własny zestaw działań, które można wykonać tylko na tym hoście. Szczegółowe informacje znajdziesz w tych przewodnikach:
Obiekty zdarzeń działania
Gdy dodatek wywoła Action, interfejs automatycznie utworzy obiekt zdarzenia JSON i przekaże go jako argument do funkcji wywołania zwrotnego Action. Ten obiekt zdarzenia zawiera informacje o bieżącym kontekście użytkownika po stronie klienta, np. bieżące wartości wszystkich interaktywnych widżetów na wyświetlanej karcie.
Obiekty zdarzeń akcji mają określoną strukturę JSON, która porządkuje zawarte w nich informacje. Ta sama struktura jest używana, gdy uruchomi się reguła związana ze stroną główną, aby utworzyć stronę główną, lub gdy uruchomi się reguła kontekstowa w celu zaktualizowania wyświetlania dodatku.
Pełne objaśnienie struktury obiektów zdarzenia znajdziesz w artykule Obiekty zdarzeń.