Działania dodatkowe umożliwiają interaktywne działanie widżetów. Tworząc działanie, określasz, co się stanie, gdy użytkownik wybierze lub zaktualizuje widżet.
W większości przypadków możesz definiować działania dodatkowe za pomocą obiektów Action udostępnianych przez usługę karty Apps Script.
Każdy element Action jest powiązany z funkcją wywołania zwrotnego podczas jej tworzenia. Stosujesz funkcję wywołania zwrotnego, aby wykonywać odpowiednie czynności, gdy użytkownik 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 rodzaj interakcji, która wywołuje wywołanie zwrotne Action.
Skonfiguruj widżet za pomocą Action, korzystając z tego ogólnego procesu:
- Utwórz obiekt
Action, określając funkcję wywołania zwrotnego, którą powinna wykonać, wraz ze wszystkimi wymaganymi parametrami. - Wywołaj odpowiednią funkcję obsługi widżetu w widżecie za pomocą obiektu
Action. - Zaimplementuj funkcję wywołania zwrotnego, aby zastosować wymagane zachowanie.
Funkcje modułu obsługi widżetów
Aby połączyć widżet z określonym elementem Action lub innym działaniem, użyj funkcji obsługi widżetów. Funkcja obsługi określa rodzaj interakcji (np. kliknięcie widżetu lub edytowanie pola tekstowego), który ma wyzwalać działanie. Funkcja ta określa też, jakie czynności wykonuje interfejs użytkownika po zakończeniu działania (jeśli jakieś występują).
W tabeli poniżej znajdziesz różne typy modułów obsługi widżetów oraz listę widżetów, z którymi są one używane:
| Funkcja obsługi | Działanie aktywatora | Można zastosować widżety | Opis |
|---|---|---|---|
setOnChangeAction() |
Wartość widżetu zmienia się |
DatePickerDateTimePickerSelectionInputSwitchTextInput
TimePicker
|
Ustawia Action, który uruchamia funkcję Apps Script, gdy widżet przestanie być aktywny, na przykład gdy użytkownik wpisze tekst i naciśnie Enter. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywołanej funkcji.
W razie potrzeby możesz wstawić w tym obiekcie zdarzenia dodatkowe informacje o parametrze. |
setOnClickAction() |
Użytkownik klika widżet. |
CardActionImageImageButtonDecoratedTextTextButton
|
Konfiguruje Action, który uruchamia funkcję Apps Script, gdy użytkownik kliknie widżet. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywołanej funkcji.
W tym obiekcie zdarzenia możesz wstawić opcjonalne informacje o parametrze. |
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. Możesz utworzyć wersję roboczą jako nową wiadomość lub odpowiedź na otwartą wiadomość w Gmailu. Gdy moduł obsługi wywołuje funkcję wywołania zwrotnego kompilacji roboczej, przekazuje do tej funkcji obiekt zdarzenia.
Więcej informacji znajdziesz w artykule Tworzenie wersji roboczych wiadomości. |
setOnClickOpenLinkAction() |
Użytkownik klika widżet. |
CardActionImageImageButtonDecoratedTextTextButton
|
Konfiguruje Action do otwierania adresu URL, gdy użytkownik kliknie widżet. Użyj tego modułu obsługi, gdy musisz utworzyć adres URL lub przed otwarciem linku trzeba wykonać inne działania. W przeciwnym razie łatwiej jest użyć elementu setOpenLink().
Adres URL możesz otworzyć tylko w nowym oknie. Zamknięcie dodatku może spowodować ponowne wczytanie dodatku w interfejsie. |
setOpenLink() |
Użytkownik klika widżet. |
CardActionImageImageButtonDecoratedTextTextButton
|
Bezpośrednio otwiera adres URL, gdy użytkownik kliknie widżet. Używaj tego modułu obsługi, jeśli znasz adres URL i chcesz go tylko otworzyć. W przeciwnym razie użyj setOnClickOpenLinkAction().
Możesz otworzyć adres URL w nowym oknie lub w nakładce. Zamknięcie dodatku może spowodować ponowne wczytanie dodatku w interfejsie. |
setSuggestionsAction() |
Użytkownik wpisuje tekst w polu do wprowadzania danych. |
TextInput
|
Konfiguruje Action, który uruchamia funkcję Apps Script, gdy użytkownik wpisze tekst w widżecie wprowadzania tekstu. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywołanej funkcji.
Więcej informacji znajdziesz w sekcji Sugestie autouzupełniania w przypadku wpisywania tekstu. |
Funkcje wywołania zwrotnego
Funkcje wywołania zwrotnego są wykonywane po uruchomieniu Action. Funkcja wywołania zwrotnego jest funkcjami Apps Script, dzięki czemu mogą wykonywać prawie wszystkie pozostałe funkcje skryptów.
Funkcja wywołania zwrotnego czasami zwraca określony obiekt odpowiedzi. Te typy odpowiedzi wskazują dodatkowe operacje, które muszą mieć miejsce po zakończeniu wywołania zwrotnego, takie jak wyświetlenie nowej karty lub pokazanie sugestii autouzupełniania. Jeśli funkcja wywołania zwrotnego musi zwracać określony obiekt odpowiedzi, możesz utworzyć ten obiekt za pomocą klasy konstruktora w usłudze karty.
W tabeli poniżej pokazujemy, kiedy funkcje wywołań zwrotnych 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:
| Podjęto próbę wykonania działania | Funkcja wywołania zwrotnego powinna zwrócić |
|---|---|
| Poruszanie się między kartami | ActionResponse |
Wyświetl Notification |
ActionResponse |
Otwórz link za pomocą aplikacji setOnClickOpenLinkAction() |
ActionResponse |
| Wyświetlanie sugestii autouzupełniania | SuggestionResponse |
| Zastosuj działanie uniwersalne. | UniversalActionResponse |
| Inne czynności | Brak |
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. Więcej informacji znajdziesz w tych przewodnikach:
Obiekty zdarzeń akcji
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 po stronie klienta, np. bieżące wartości wszystkich interaktywnych widżetów na wyświetlanej karcie.
Obiekty zdarzeń akcji mają specyficzną strukturę JSON, która porządkuje zawarte w nich informacje. Ta sama struktura jest stosowana, gdy uruchamia się reguła strony głównej, aby utworzyć stronę główną, lub gdy uruchamia się reguła kontekstowa, aby zaktualizować ekran dodatku.
Pełne informacje o strukturze obiektów zdarzeń znajdziesz w sekcji Obiekty zdarzeń.