Działania dodatkowe

Działania dodatkowe umożliwiają interaktywne działanie widżety. Tworząc działanie, określasz, co się stanie, gdy użytkownik wybierze lub zaktualizuje aplikację. lub widżet.

Działania dodatkowe można w większości przypadków zdefiniować za pomocą Action obiekty udostępniane przez usługę karty Apps Script. Każda jednostka Action jest powiązana z: funkcji wywołania zwrotnego podczas jej tworzenia. Ty implementujesz funkcję wywołania zwrotnego na wykonanie pożądanych działań, gdy użytkownik wejdzie w interakcję z widżetem. Musisz też Połącz usługę Action z widżetem za pomocą odpowiedniej funkcji obsługi widżetów, która określa rodzaj interakcji, która wywołuje Action – wywołanie zwrotne.

Konfigurowanie widżetu przy użyciu Action w ten sposób:

1. Utwórz obiekt Action. określając funkcję wywołania zwrotnego, która powinna wraz z wszystkimi wymaganymi parametrami.
2. Wywołaj odpowiednią funkcję obsługi widżetu w widżecie za pomocą funkcji Action obiektu.
3. Zaimplementuj funkcję wywołania zwrotnego, aby wywołać wymagane zachowanie.

Uwaga: nie myl Action. obiekty z funkcją CardAction obiektów. CardAction obiektów to pozycje menu w nagłówku karty, a Action definiują odpowiedzi na interakcje użytkowników z interfejsem.

Funkcje obsługi widżetów

Aby połączyć widżet z konkretnym elementem Action lub innego sposobu działania, można użyć widżetu . Rodzaj interakcji określa funkcja obsługi (na przykład kliknięcie widżetu lub edycja pola tekstowego) powoduje uruchomienie wywołania zachowanie użytkownika. Moduł obsługi definiuje też czynności wykonywane przez interfejs użytkownika, po zakończeniu działania.

W tabeli poniżej znajdziesz różne typy modułów obsługi widżetów oraz listę funkcji, widżety, w których są używane:

Funkcja obsługi	Działanie aktywujące	Dostępne widżety	Opis
setOnChangeAction()	Wartość widżetu zmienia się	DatePicker DateTimePicker SelectionInput Switch TextInput TimePicker	Ustawia: Action uruchamiającą funkcję Apps Script, gdy widżet straci zaznaczenie, np. na przykład po wpisaniu tekstu i naciśnięciu Entera. moduł obsługi automatycznie przekazuje event do wywoływanej funkcji. W tym obiekcie zdarzenia możesz wstawić dodatkowe informacje o parametrach w razie potrzeby.
setOnClickAction()	Użytkownik klika widżet.	CardAction Image ImageButton DecoratedText TextButton	Ustawia: Action uruchamiającą funkcję Apps Script, gdy użytkownik kliknie widżet. moduł obsługi automatycznie przekazuje event do wywoływanej funkcji. W tym obiekcie zdarzenia możesz wstawić opcjonalne informacje o parametrach.
setComposeAction()	Użytkownik klika widżet.	CardAction Image ImageButton DecoratedText TextButton	Dotyczy tylko Gmaila. Ustawia wartość Action który tworzy wersję roboczą e-maila, a potem wyświetla użytkownikowi Okno tworzenia wiadomości w interfejsie Gmaila. Wersję roboczą możesz utworzyć jako nową wiadomość odpowiedz na otwartą wiadomość w Gmailu. Gdy moduł obsługi wywołuje metodę funkcji wywołania zwrotnego tworzenia wersji roboczej, przekazuje event do funkcji wywołania zwrotnego. Zobacz Tworzenie wersji roboczych wiadomości .
setOnClickOpenLinkAction()	Użytkownik klika widżet.	CardAction Image ImageButton DecoratedText TextButton	Ustawia: Action , aby otwierać adres URL, gdy użytkownik kliknie widżet. Używaj tego modułu obsługi, gdy: musi utworzyć adres URL, a inne działania muszą zostać wykonane przed linkiem otwiera się; w przeciwnym razie zwykle prościej jest użyć setOpenLink(). Ten adres URL możesz otworzyć tylko w nowym oknie. Po zamknięciu może być aby ponownie załadować dodatek.
setOpenLink()	Użytkownik klika widżet.	CardAction Image ImageButton DecoratedText TextButton	Otwiera bezpośrednio adres URL, gdy użytkownik kliknie widżet. Użyj tej , jeśli znasz adres URL i wystarczy go otworzyć; w inny sposób użyj setOnClickOpenLinkAction() Możesz otworzyć adres URL w nowym oknie lub w nakładce. Po zamknięciu może spowodować ponowne załadowanie dodatku w interfejsie.
setSuggestionsAction()	Użytkownik wpisuje tekst.	TextInput	Ustawia: Action która uruchamia funkcję Apps Script, gdy użytkownik wpisze widżetem wprowadzania tekstu. Moduł obsługi automatycznie przekazuje event do wywoływanej funkcji. Zobacz Sugestie autouzupełniania do wprowadzania tekstu.

Funkcje wywołania zwrotnego

Funkcje wywołania zwrotnego są wykonywane, gdy Action wyzwalaczy. Ponieważ funkcja wywołania zwrotnego jest funkcjami Apps Script, można je wykonywać praktycznie to samo, co inna funkcja skryptu.

Ostrzeżenie: usługa kart Apps Script ogranicza funkcje wywołania zwrotnego do maksymalnie 30 sekund wykonywania. Jeśli trwa to dłużej, więc interfejs użytkownika dodatku może nie zaktualizować wyświetlają się prawidłowo w odpowiedzi na Action.

Funkcja wywołania zwrotnego czasem zwraca określony obiekt odpowiedzi. Te Typy odpowiedzi wskazują dodatkowe operacje, które muszą zostać wykonane po wywołanie zwrotne dobiega końca, np. wyświetla nową kartę lub prezentację. sugestie autouzupełniania. Kiedy funkcja wywołania zwrotnego musi zwrócić określony , użyj klasy konstruktora w usłudze karty. do jego skonstruowania.

W tabeli poniżej pokazujemy, kiedy funkcje wywołania zwrotnego muszą zwracać błąd dla określonych działań. Wszystkie te działania niezależnie od konkretnej aplikacji hosta, który jest rozszerzany 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 czynności, które można wykonywać tylko na tym hoście. Więcej informacji: przewodniki:

• Działania w kalendarzu
• Działania na Dysku
• Działania w Gmailu
• Działania edytora

Uwaga: podczas korzystania z klas kreatora odpowiedzi pamiętaj o wywoływaniu build() do tworzyć obiekty odpowiedzi. Jeśli tego nie zrobisz, wystąpi błąd.

Uwaga: działania uniwersalne są zdefiniowane w pliku manifestu projektu i nie potrzebujesz Action. obiektów, ale ich funkcje wywołania zwrotnego muszą zwracać UniversalActionResponse.

Obiekty zdarzeń działania

Gdy dodatek wywoła Action, interfejs automatycznie tworzy obiekt zdarzenia JSON i przekazuje go jako argument w wywołaniu zwrotnym Action . Ten obiekt zdarzenia zawiera informacje o bieżącej aktywności użytkownika po stronie klienta, np. bieżące wartości wszystkich elementów interaktywnych, widżety 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 reguła strony głównej uruchamia się w celu utworzenia strony głównej, reguła kontekstowa zostanie uruchomiony, aby zaktualizować wyświetlacz dodatku.

Pełną listę znajdziesz w sekcji Obiekty zdarzeń. i lepiej poznać strukturę obiektów zdarzenia.

Uwaga: dodatki do Gmaila używały uproszczonej wersji struktury obiektów zdarzenia. który został już wycofany. Aby zachować zgodność wsteczną, wszystkie modele Pola obiektów wydarzenia dodatków w Gmailu nadal znajdują się w nowym zdarzeniu strukturze obiektu (zobacz strukturę obiektów zdarzeń). Te same informacje są jednak powtarzane w typowe zdarzenie i wydarzenie w Gmailu podstruktury obiektów. Jeśli uaktualniasz dodatek Gmaila do dodatku Google Workspace, dostosuj swój kod aby używać zaktualizowanych pól obiektów zdarzenia – ostatecznie .