Działania dodatkowe

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:

1. Utwórz obiekt Action, podając funkcję wywołania zwrotnego, którą ma wykonać, wraz z wymaganymi parametrami.
2. Wywołaj odpowiednią funkcję obsługi widżetu na widżecie za pomocą obiektu Action.
3. Zaimplementuj funkcję wywołania zwrotnego, aby uzyskać wymagane działanie.

Uwaga: nie należy mylić obiektów Action z obiektami CardAction. Obiekty CardAction to elementy menu nagłówka karty, a obiekty Action definiują odpowiedzi na interakcje użytkownika z interfejsem.

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.	DatePicker DateTimePicker SelectionInput Switch TextInput 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	CardAction Image ImageButton DecoratedText TextButton	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	CardAction Image ImageButton DecoratedText TextButton	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	CardAction Image ImageButton DecoratedText TextButton	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	CardAction Image ImageButton DecoratedText TextButton	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.

Ostrzeżenie: skrypt Apps Script usługa kart ogranicza czas wykonywania funkcji wywołania do maksymalnie 30 sekund. Jeśli wykonanie trwa dłużej, interfejs dodatku może nie zaktualizować wyświetlania karty w odpowiedzi na Action.

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:

• Działania w kalendarzu
• Działania na Dysku
• Działania w Gmailu
• Działania edytujące

Uwaga: gdy używasz klas kreatora odpowiedzi, wywołaj metodę build(), aby utworzyć obiekty odpowiedzi. Jeśli tego nie zrobisz, wystąpi błąd.

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

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.

Uwaga: dodatki do Gmaila używały uproszczonej wersji tej struktury obiektu zdarzenia, która została wycofana. Ze względu na zgodność wsteczną wszystkie oryginalne pola obiektu zdarzenia dodatków Gmaila są nadal zawarte w nowej strukturze obiektu zdarzenia (patrz struktura obiektu zdarzenia). Te same informacje są jednak powielane w strukturach podrzędnych obiektów odrębnego zdarzenia i zdarzenia Gmaila. Jeśli chcesz przekształcić dodatek Gmaila w dodatek Google Workspace, musisz dostosować kod, aby używać zaktualizowanych pól obiektu wydarzenia. Ostatecznie oryginalne pola obiektu wydarzenia w Gmailu zostaną usunięte.