Działania dodatkowe

Czynności dodatkowe umożliwiają interaktywne korzystanie z widżetów. Tworząc działanie, określasz, co użytkownik wybierze lub zaktualizuje.

W większości przypadków działania dodatkowe można definiować za pomocą obiektów Action udostępnianych przez usługę karty Apps Script. Każdy utworzony element Action jest powiązany z funkcją wywołania zwrotnego. Zaimplementujesz funkcję wywołania zwrotnego, aby wykonać odpowiednie czynności, gdy użytkownik wejdzie w interakcję z widżetem. Musisz też połączyć Action z widżetem za pomocą odpowiedniej funkcji obsługi widżetów, która określa rodzaj interakcji wywołującej wywołanie zwrotne Action.

Skonfiguruj widżet z Action w ten sposób:

  1. Utwórz obiekt Action, określając funkcję wywołania zwrotnego, która powinna zostać wykonana wraz z wymaganymi parametrami.
  2. Wywołaj odpowiednią funkcję obsługi widżetów na widżecie za pomocą obiektu Action.
  3. Zaimplementuj funkcję wywołania zwrotnego, aby wprowadzić wymagane działanie.

Funkcje obsługi widżetów

Aby połączyć widżet z konkretnym elementem Action lub innym sposobem, 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óra wywołuje działanie. Funkcja obsługi określa też, co użytkownik musi zrobić po wykonaniu działania w interfejsie.

W tabeli poniżej znajdziesz różne rodzaje modułów obsługi widżetów oraz ich widżety:

Funkcja obsługi Działanie reguły Dostępne widżety Opis
setOnChangeAction() Zmiana wartości widżetu DatePicker
DateTimePicker
SelectionInput
Switch
TextInput TimePicker
Ustawia element Action, który uruchamia funkcję Apps Script, gdy widżet traci fokus, na przykład gdy użytkownik wpisze tekst w danych wejściowych i naciśnie Enter. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej funkcji. W razie potrzeby możesz wstawić dodatkowe informacje o parametrze w tym obiekcie zdarzenia.
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. 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 Action, który tworzy wersję roboczą e-maila, a następnie wyświetla tę wersję użytkownikowi w oknie tworzenia interfejsu Gmaila. Wersję roboczą możesz utworzyć jako nową wiadomość lub w odpowiedzi na otwartą wiadomość w Gmailu. Gdy moduł obsługi wywołuje funkcję wywołania zwrotnego kompilacji roboczej, przekazuje do obiektu wywołania zwrotnego 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 tak, aby użytkownik otwierał adres URL, gdy kliknie widżet. Użyj tej instrukcji obsługi, gdy musisz utworzyć adres URL. W przeciwnym razie działanie musi zostać wykonane przed otwarciem linku. W przeciwnym razie zazwyczaj łatwiej jest użyć setOpenLink(). URL możesz otworzyć tylko w nowym oknie. Gdy to zrobisz, możesz ponownie wczytać 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 tego modułu obsługi, gdy znasz adres URL i musisz go otworzyć. W przeciwnym razie użyj setOnClickOpenLinkAction(). URL możesz otworzyć w nowym oknie lub w nakładce. Gdy to zrobisz, możesz ponownie wczytać dodatek.
setSuggestionsAction() Użytkownik wpisuje tekst. TextInput Ustawia element Action, który wykonuje funkcję Apps Script, gdy użytkownik wpisuje tekst do widżetu do wprowadzania tekstu. Moduł obsługi automatycznie przekazuje obiekt zdarzenia do wywoływanej funkcji. Więcej informacji znajdziesz w artykule na temat autouzupełniania sugestii dotyczących wprowadzania tekstu.

Funkcje wywołania zwrotnego

Funkcje wywołania zwrotnego są uruchamiane po uruchomieniu aktywatora Action. Funkcja wywołania zwrotnego to funkcja Apps Script, więc można ją wykorzystać do prawie każdej funkcjonalności skryptu.

Funkcja wywołania zwrotnego czasami zwraca określony obiekt odpowiedzi. Tego rodzaju odpowiedzi wskazują dodatkowe operacje, które muszą zostać wykonane po zakończeniu wywołania zwrotnego, takie jak wyświetlanie nowej karty lub wyświetlanie sugestii autouzupełniania. Gdy funkcja wywołania zwrotnego musi zwrócić określony obiekt odpowiedzi, do utworzenia tego obiektu używasz klasy kreatora w usłudze karty.

Poniższa tabela pokazuje, kiedy funkcje zwrotne muszą zwrócić określony obiekt odpowiedzi dla określonych działań. Te czynności są niezależne od konkretnego hosta, który obejmuje dany dodatek:

Podjęto działanie Funkcja wywołania zwrotnego powinna być zwrócona
Nawigacja między kartami ActionResponse
Wyświetl Notification ActionResponse
Otwieranie linku za pomocą setOnClickOpenLinkAction() ActionResponse
Wyświetlanie sugestii autouzupełniania SuggestionResponse
Użyj działania uniwersalnego UniversalActionResponse
Inne czynności Brak

Poza tymi działaniami każda aplikacja hosta ma własny zestaw działań, które można wykonywać tylko na tym hoście. Szczegółowe informacje znajdziesz w tych przewodnikach:

Obiekty zdarzeń działania

Gdy dodatek aktywuje Action, interfejs użytkownika automatycznie tworzy obiekt zdarzenia w formacie JSON i przekazuje go jako argument do funkcji wywołania zwrotnego Action. Ten obiekt zdarzenia zawiera informacje o bieżącym kontekście użytkownika po stronie klienta, np. o bieżących wartościach wszystkich interaktywnych widżetów na wyświetlanej karcie.

Obiekty zdarzeń działania mają określoną strukturę JSON, w której znajdują się zawarte w nich informacje. Ta sama struktura jest używana, gdy reguła strony głównej uruchamia się na stronie głównej lub gdy reguła kontekstowa uruchamia aktualizację dodatku.

Szczegółowe informacje o strukturze obiektów zdarzeń znajdziesz w artykule Obiekty zdarzeń.