Działania dodatku zapewniają interaktywność 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 działania dodatku możesz zdefiniować za pomocą obiektów Action udostępnianych przez usługę kart Google Apps Script.
Każdy Action jest powiązany z funkcją wywołania zwrotnego podczas tworzenia. Funkcję wywołania zwrotnego implementujesz, aby wykonać wybrane czynności, gdy użytkownik wchodzi w interakcję z widgetem. Musisz też połączyć Action z widżetem za pomocą odpowiedniej funkcji obsługi widżetu, która określa, jaki rodzaj interakcji wywołuje wywołanie zwrotne Action.
Skonfiguruj widżet z Action, wykonując te czynności:
- Utwórz obiekt
Action, określając funkcję wywołania zwrotnego, którą ma wykonać, oraz wszystkie wymagane parametry. - Wywołaj odpowiednią funkcję obsługi widżetu w widżecie za pomocą obiektu
Action. - Zaimplementuj funkcję wywołania zwrotnego, aby wdrożyć wymagane działanie.
Nie myl obiektów Action z obiektami CardAction. CardAction obiekty to elementy menu nagłówka karty, a obiekty Action definiują odpowiedzi na interakcje użytkownika z interfejsem.
Funkcje obsługi widżetów
Aby połączyć widżet z Action lub innym działaniem, użyj funkcji obsługi widżetu. Funkcja obsługi określa, jaki rodzaj interakcji (np. kliknięcie widżetu lub edytowanie pola tekstowego) wywołuje działanie. Funkcja obsługi określa też, jakie kroki (jeśli w ogóle) podejmuje interfejs po zakończeniu działania.
W tabeli poniżej znajdziesz różne typy modułów obsługi widżetów i informacje o tym, z jakimi widżetami są one używane:
| Funkcja obsługi | Wywołuje działanie | Widżety, których dotyczy problem | Opis |
|---|---|---|---|
setOnChangeAction |
Wartość widżetu się zmienia |
DatePicker
DateTimePicker
SelectionInputSwitch
TextInput
TimePicker
|
Ustawia Action, która wykonuje funkcję Apps Script, gdy widżet traci fokus, np. gdy użytkownik wpisze tekst w polu i naciśnie Enter. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej funkcji.
W tym obiekcie zdarzenia możesz wstawić dodatkowe informacje o parametrach, jeśli je wybierzesz. |
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 Gmaila. Ustawia
Action
, która tworzy wersję roboczą e-maila, a następnie wyświetla ją użytkownikowi w oknie tworzenia wiadomości w interfejsie Gmaila. Wersję roboczą możesz utworzyć jako nową wiadomość lub odpowiedź na otwartą wiadomość w Gmailu. Gdy moduł obsługi wywołuje funkcję wywołania zwrotnego tworzenia 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, aby otworzyć adres URL, gdy użytkownik kliknie widżet. Używaj tego modułu obsługi, gdy musisz utworzyć adres URL lub wykonać inne działania przed otwarciem linku. W przeciwnym razie zwykle prościej jest użyć setOpenLink.
Adres URL możesz otworzyć tylko w nowym oknie. Po zamknięciu możesz spowodować ponowne załadowanie dodatku w interfejsie. |
setOpenLink |
Użytkownik klika widżet. |
CardActionImageImageButtonDecoratedTextTextButton
|
Bezpośrednie otwieranie adresu URL, gdy użytkownik kliknie widżet. Używaj tego modułu obsługi, gdy znasz adres URL i musisz go tylko otworzyć. W przeciwnym razie użyj setOnClickOpenLinkAction.
Możesz otworzyć adres URL w nowym oknie lub w nakładce. Po zamknięciu możesz spowodować ponowne załadowanie dodatku przez interfejs. |
setSuggestionsAction |
Użytkownik wpisuje tekst w polu wejściowym. |
TextInput
|
Ustawia Action, która wykonuje funkcję Apps Script, gdy użytkownik wpisuje tekst w widżecie wprowadzania tekstu. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej funkcji.
Więcej informacji znajdziesz w artykule Podpowiedzi autouzupełniania w przypadku wprowadzania tekstu. |
Funkcje wywołania zwrotnego
Funkcje wywołania zwrotnego są wykonywane, gdy aktywuje się Action. Funkcje wywołania zwrotnego są funkcjami Apps Script, więc mogą robić prawie wszystko, co inne funkcje skryptu.
Funkcja wywołania zwrotnego czasami zwraca konkretny obiekt odpowiedzi. Te typy odpowiedzi wskazują dodatkowe operacje, które muszą zostać wykonane po zakończeniu wywołania zwrotnego, np. wyświetlenie nowej karty lub sugestii autouzupełniania. Gdy funkcja wywołania zwrotnego musi zwrócić konkretny obiekt odpowiedzi, użyj klasy konstruktora w usłudze Card, aby utworzyć ten obiekt.
W tabeli poniżej znajdziesz informacje o tym, 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ęte działanie | Funkcja wywołania zwrotnego powinna zwracać |
|---|---|
| Nawigacja | ActionResponse |
Wyświetlanie Notification |
ActionResponse |
Otwieranie linku za pomocą setOnClickOpenLinkAction |
ActionResponse |
| Wyświetlanie sugestii autouzupełniania | SuggestionResponse |
| Używanie działania uniwersalnego | UniversalActionResponse |
| Inne czynności | Nothing |
Działania w aplikacjach hosta Google Workspace
Oprócz tych działań każda aplikacja hosta ma własny zestaw działań, które można wykonać tylko w tej aplikacji. Więcej informacji znajdziesz w tych przewodnikach:
Podczas korzystania z klas narzędzia do tworzenia odpowiedzi wywołaj metodę build, aby utworzyć obiekty odpowiedzi. W przeciwnym razie wystąpi błąd.
Działania uniwersalne są zdefiniowane w pliku manifestu projektu i nie wymagają obiektów Action, ale ich funkcje wywołania zwrotnego muszą zwracać obiekt UniversalActionResponse.
Obiekty zdarzeń działania
Gdy dodatek wywoła Action, interfejs automatycznie utworzy obiekt zdarzenia JSON i przekaże go jako argument do wywołania zwrotnego Action. Ten obiekt zdarzenia zawiera informacje o bieżącym kontekście po stronie klienta użytkownika, takie jak bieżące wartości wszystkich interaktywnych widżetów na wyświetlanej karcie.
Obiekty zdarzeń związanych z działaniami 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 się w celu utworzenia strony głównej lub gdy reguła kontekstowa uruchamia się w celu zaktualizowania wyświetlania dodatku.
Pełne wyjaśnienie struktury obiektu zdarzenia znajdziesz w sekcji Obiekty zdarzeń.
Dodatki do Gmaila korzystały z uproszczonej wersji tej struktury obiektu zdarzenia, która została wycofana. Ze względu na zgodność wsteczną wszystkie oryginalne pola obiektu zdarzenia dodatków do Gmaila są nadal zawarte w nowej strukturze obiektu zdarzenia (patrz struktura obiektu zdarzenia).
Te same informacje są jednak powielane w podstrukturach obiektów commonEventObjecti Gmail event. Jeśli uaktualniasz dodatek do Gmaila do dodatku do Google Workspace, dostosuj kod, aby używać zaktualizowanych pól obiektu zdarzenia. Ostatecznie pola pierwotnego obiektu wydarzenia w Gmailu zostaną usunięte.