Działania dodatkowe

Działania dodatku zapewniają 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 zdefiniować działania dodatku za pomocą obiektów Action udostępnianych przez usługę kart Apps Script. Każdy Action jest powiązany z funkcją wywołania zwrotnego podczas jego tworzenia. Funkcję wywołania zwrotnego implementujesz, aby wykonać wybrane kroki, 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 ogólne czynności:

1. Utwórz obiekt Action, określając funkcję wywołania zwrotnego, którą ma wykonać, oraz wszelkie wymagane parametry.
2. Wywołaj odpowiednią funkcję obsługi widżetu w widżecie za pomocą obiektu Action.
3. Zaimplementuj funkcję wywołania zwrotnego, aby wdrożyć wymagane działanie.

Uwaga: nie myl obiektów Action z obiektami CardAction. Obiekty CardAction to elementy menu nagłówka karty, a obiekty Action określają odpowiedzi na interakcje użytkownika z interfejsem.

Funkcje obsługi widżetów

Aby połączyć widżet z określonym 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 ma wykonać interfejs, jeśli w ogóle, 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	Odpowiednie widżety	Opis
setOnChangeAction()	Wartość widżetu się zmienia	DatePicker DateTimePicker SelectionInput Switch 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.	CardAction Image ImageButton DecoratedText TextButton	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. Do tego obiektu zdarzenia możesz wstawić opcjonalne informacje o parametrach.
setComposeAction()	Użytkownik klika widżet.	CardAction Image ImageButton DecoratedText TextButton	Dotyczy Gmaila. Ustawia Action , która tworzy wersję roboczą e-maila, a następnie wyświetla ją użytkownikowi w oknie tworzenia 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.	CardAction Image ImageButton DecoratedText TextButton	Ustawia Action, aby po kliknięciu widżetu przez użytkownika otworzyć adres URL. Używaj tego modułu obsługi, gdy musisz utworzyć adres URL lub wykonać inne działania przed otwarciem linku. W przeciwnym razie zwykle łatwiej jest użyć setOpenLink(). Adres URL możesz otworzyć tylko w nowym oknie. Po zamknięciu możesz spowodować ponowne załadowanie dodatku przez interfejs.
setOpenLink()	Użytkownik klika widżet.	CardAction Image ImageButton DecoratedText TextButton	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 innym przypadku 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 wpisywania tekstu.

Funkcje wywołania zwrotnego

Funkcje wywołania zwrotnego są wykonywane, gdy aktywuje się Action. Funkcje wywołania zwrotnego to funkcje Apps Script, więc mogą robić prawie wszystko, co inne funkcje skryptu.

Ostrzeżenie: w usłudze Card service Apps Script czas wykonywania funkcji zwrotnych jest ograniczony do 30 sekund. Jeśli wykonanie trwa dłużej, interfejs dodatku może nie aktualizować prawidłowo wyświetlania karty w odpowiedzi na Action

.

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 konkretnych 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ć
Przechodzenie między kartami	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:

• Działania w Kalendarzu
• Działania na czacie
• Działania na Dysku
• Działania w Gmailu
• Działania edytującego

Uwaga: gdy używasz klas narzędzia do tworzenia odpowiedzi, pamiętaj, aby wywołać funkcję build(), aby utworzyć obiekty odpowiedzi. Jeśli tego nie zrobisz, pojawi się błąd.

Uwaga: działania uniwersalne są zdefiniowane w manifeście projektu i nie wymagają obiektów Action, ale ich funkcje wywołań zwrotnych muszą zwracać wartość UniversalActionResponse.

Obiekty zdarzeń związanych z działaniami

Gdy dodatek wywoła Action, interfejs automatycznie utworzy obiekt zdarzenia JSON event object i przekaże go jako argument do funkcji zwrotnej 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świetlonej 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 uruchamia się reguła strony głównej, aby utworzyć stronę główną, lub gdy uruchamia się reguła kontekstowa, aby zaktualizować wyświetlanie dodatku.

Pełne wyjaśnienie struktury obiektu zdarzenia znajdziesz w sekcji Obiekty zdarzeń.

Uwaga: dodatki do Gmaila używały uproszczonej wersji tej struktury obiektu zdarzenia, która jest obecnie 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 common event i Gmail event. Jeśli uaktualniasz dodatek do Gmaila do dodatku do Google Workspace, dostosuj kod, aby używać zaktualizowanych pól obiektu zdarzenia. Oryginalne pola obiektu zdarzenia Gmaila zostaną ostatecznie usunięte.