Wyzwalacze Apps Script powodują wykonywanie określonej funkcji skryptu (funkcji aktywatora), gdy wystąpi określone zdarzenie. Tylko określone zdarzenia mogą wywoływać reguły, a każda aplikacja Google Workspace obsługuje inny zestaw zdarzeń.
Po uruchomieniu reguły tworzony jest obiekt zdarzenia. Ta struktura JSON zawiera szczegółowe informacje o tym zdarzeniu. Informacje w strukturze obiektów zdarzeń są uporządkowane inaczej w zależności od typu aktywatora.
Po utworzeniu obiektu zdarzenia Apps Script przekazuje go jako parametr do funkcji aktywatora. Funkcja aktywująca to funkcja wywołania zwrotnego, którą musisz zaimplementować samodzielnie, aby wykonywać działania odpowiadające na żądanie. Na przykład w dodatku Edytor służy do tworzenia pozycji menu dodatków po otwarciu dokumentu. W tym przypadku wdrożysz funkcję aktywatora onOpen(e)
, aby utworzyć potrzebne pozycje menu, które mogą być dodatkiem, prawdopodobnie używając danych z obiektu zdarzenia.
Na tej stronie znajdziesz wskazówki dotyczące używania aktywatorów w projektach dodatków edytora.
Rodzaje reguł dodatku do edytora
W dodatkach do edytorów możesz używać większości ogólnych typów aktywatorów dostępnych w projektach Apps Script, w tym prostych reguł i większości instalacyjnych reguł. Dokładny zestaw dostępnych typów aktywatorów zależy od rozszerzenia aplikacji.
W tabeli poniżej znajdziesz typy prostych i instalacyjnych reguł, których mogą używać dodatki do edytora, oraz linki do odpowiadających im obiektów zdarzeń:
Zdarzenie | Obiekt zdarzenia | Proste aktywatory | Reguły możliwe do zainstalowania |
---|---|---|---|
Otwórz Zostanie otwarty plik edytora. |
Obiekt zdarzenia onOpen Obiekt zdarzenia onOpen Obiekt zdarzenia onOpen Obiekt zdarzenia Prezentacji onOpen |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Zainstaluj Dodatek jest zainstalowany. |
Obiekt zdarzenia onInstall |
![]() ![]() ![]() ![]()
|
|
Edytuj Treść komórki arkusza kalkulacyjnego zostanie zmieniona. |
Obiekt zdarzenia onEdit |
![]()
|
![]() |
Zmień Treść arkusza jest edytowana lub formatowana. |
Obiekt zdarzenia onChange w Arkuszach |
![]() |
|
Przesłanie formularza Przesyłany jest formularz Google. |
Zdarzenie: przesłanie formularza z użyciem Formularzy Zdarzenie typu „Przesłanie formularza” |
![]() ![]() |
|
Na podstawie czasu (zegar) Reguła uruchamia się o określonej godzinie lub w określonym przedziale czasu. |
Obiekt zdarzeń ograniczonych czasowo |
![]() ![]() ![]() ![]() |
* Zdarzenie otwarte w Formularzach Google nie występuje, gdy użytkownik otwiera formularz, tylko odpowiada, gdy edytuje formularz, aby go zmodyfikować.
Proste aktywatory w dodatkach
Proste aktywatory używają zdefiniowanych nazw funkcji, nie mogą korzystać z usług, które wymagają autoryzacji, i są automatycznie włączane do użytku. W niektórych przypadkach proste zdarzenie aktywujące może być obsługiwane przez instalację reguły.
Możesz dodać prosty dodatek do dodatku, implementując funkcję z jedną z tych zarezerwowanych nazw:
onOpen(e)
jest uruchamiany, gdy użytkownik otworzy dokument, arkusz kalkulacyjny lub prezentację.onOpen(e)
może też wykonać się po otwarciu formularza w edytorze (ale nie podczas odpowiadania na formularz). Wykonywana jest tylko wtedy, gdy użytkownik ma uprawnienia do edycji danego pliku, i najczęściej jest używana do tworzenia pozycji menu.onInstall(e)
jest wykonywany, gdy użytkownik zainstaluje dodatek. Zazwyczaj funkcjaonInstall(e)
jest używana do wywołania metodyonOpen(e)
. Dzięki temu menu dodatków pojawia się od razu po zainstalowaniu, bez potrzeby odświeżania strony przez użytkownika.onEdit(e)
działa, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ten aktywator nie jest uruchamiany w odpowiedzi na przenoszenie komórki, formatowanie lub inne zmiany, które nie zmieniają wartości komórek.
Ograniczenia
Proste aktywatory w dodatkach podlegają tym samym ograniczeniom, które regulują proste reguły w innych typach projektów Apps Script. Podczas projektowania dodatków weź pod uwagę te ograniczenia:
- Proste reguły nie są uruchamiane, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie). To działanie zapobiega wypełnianiu menu dodatków.
- W pewnych okolicznościach dodatki do edytora uruchamiają proste aktywatory
onOpen(e)
ionEdit(e)
w trybie bez autoryzacji. Ten tryb wiąże się z pewnymi komplikacjami, zgodnie z modelem autoryzacji dodatków. - Proste aktywatory nie mogą używać usług ani wykonywać innych działań, które wymagają autoryzacji, z wyjątkiem sytuacji opisanych w modelu autoryzacji dodatkowego.
- Proste reguły mogą trwać maksymalnie 30 sekund. Staraj się minimalizować ilość przetwarzania wykonywanego za pomocą prostej funkcji aktywatora.
- Proste aktywatory podlegają limitom limitów aktywatorów Apps Script.
Reguły do zainstalowania w dodatkach
Dodatki mogą automatycznie tworzyć i modyfikować aktywatory instalowane za pomocą usługi Apps Script Script
. Aktywatorów uruchamiających dodatki nie można tworzyć ręcznie. Inaczej niż w przypadku prostych aktywatorów, które można zainstalować, można używać usług wymagających autoryzacji.
Reguły możliwe do zainstalowania w dodatkach nie wysyłają do użytkownika e-maili z błędami, ponieważ w większości przypadków użytkownik nie jest w stanie rozwiązać problemu. Dlatego zaprojektuj dodatek tak, aby w miarę możliwości obsługiwał błędy w imieniu użytkownika.
Dodatki mogą używać następujących aktywatorów:
- Wyzwalacze otwarte są uruchamiane, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub formularz w edytorze (ale nie podczas odpowiadania na formularz).
- Edytuj reguły możliwe do zainstalowania, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie uruchamia się w odpowiedzi na formatowanie ani inne zmiany, które nie zmieniają wartości komórek.
- Wyzwalacze montowania, które można zainstalować, są wykonywane, gdy użytkownik wprowadza jakiekolwiek zmiany w arkuszu kalkulacyjnym, między innymi formatowanie i modyfikacje samego arkusza kalkulacyjnego (np. przez dodanie wiersza).
Reguły, które można zainstalować za pomocą przesyłania formularza, są wykonywane po przesłaniu odpowiedzi z formularza Google.
Reguły oparte na czasie (nazywane też wyzwalaczami zegara) uruchamiają się o określonej godzinie lub wielokrotnie w określonych odstępach czasu.
Autoryzowanie aktywatorów możliwych do zainstalowania
Normalnie jeśli deweloper zaktualizuje dodatek, aby korzystał z nowych usług, które wymagają dodatkowej autoryzacji, użytkownicy zobaczą prośbę o ponowne uwierzytelnienie dodatku przy kolejnym użyciu.
W przypadku dodatków, które korzystają z aktywatorów, obowiązują specjalne wymagania dotyczące autoryzacji. Wyobraź sobie dodatek, który korzysta z reguły do monitorowania przesyłania formularzy: twórca formularza może autoryzować dodatek po pierwszym użyciu, a następnie pozostawić go na kilka miesięcy lub lat, nie otwierając ponownie formularza. Gdy twórca dodatku zaktualizuje dodatek i zacznie używać nowych usług, które wymagają dodatkowej autoryzacji, twórca formularza nie zobaczy okna z prośbą o ponowną autoryzację, bo nigdy nie otworzy go ponownie, a dodatek przestanie działać.
W odróżnieniu od aktywatorów w zwykłych projektach Apps Script, aktywatory w dodatkach będą nadal uruchamiane, nawet jeśli będą wymagały ponownej autoryzacji. Skrypt nadal jednak nie powiedzie się, jeśli osiągnie wiersz kodu, który wymaga autoryzacji. Aby uniknąć tej sytuacji, deweloperzy mogą użyć metody ScriptApp.getAuthorizationInfo()
, aby odblokować dostęp do części kodu, które zostały zmienione między opublikowanymi wersjami dodatku.
Poniżej znajdziesz przykład zalecanej struktury, której należy używać w funkcjach aktywatora, aby uniknąć problemów z autoryzacją. Przykładowa funkcja uruchamiająca odpowiada na przesłanie formularza za pomocą dodatku do Arkuszy Google i, jeśli wymagane jest ponowne uwierzytelnienie, wysyła do użytkownika e-maila z alertem przy użyciu szablonu HTML.
Kod.gs
autoryzacja_e-mail.html
Ograniczenia
Reguły, które można zainstalować w dodatkach, podlegają takim samym ograniczeniom, które regulują uruchamianie reguł w innych typach projektów Apps Script.
Oprócz tych ograniczeń w instalacjach uwzględniających dodatek mają zastosowanie te ograniczenia:
- Każdy dodatek może mieć tylko jedną regułę każdego typu na użytkownika na dokument. Na przykład w danym arkuszu kalkulacyjnym dany użytkownik może mieć tylko jedną regułę edycji, ale w jednym arkuszu może też mieć aktywator przesłania formularza lub regułę opartą na czasie. Inny użytkownik mający dostęp do tego samego arkusza kalkulacyjnego może mieć własny zestaw aktywatorów.
- Dodatki mogą tworzyć aktywatory tylko dla pliku, w którym jest używany. Oznacza to, że dodatek używany w dokumencie Google A nie może utworzyć reguły monitorowania po otwarciu dokumentu Google B.
- Reguły oparte na czasie nie mogą być uruchamiane częściej niż raz na godzinę.
- Dodatki nie wysyłają automatycznie e-maila, gdy kod uruchamiany przez możliwy do zainstalowania aktywator generuje wyjątek. To do dewelopera należy kontrola i sprawne rozwiązywanie problemów.
- Reguły dodatku przestaną się uruchamiać w tych sytuacjach:
- Jeśli użytkownik odinstaluje dodatek,
- Jeśli dodatek jest wyłączony w dokumencie (jeśli zostanie ponownie włączony, reguła znowu stanie się aktywna) lub
- Deweloper cofnie publikację dodatku lub prześle jego uszkodzoną wersję do sklepu z dodatkami.
- Funkcje aktywatora dodatkowego są wykonywane, dopóki nie osiągną kodu, który powoduje użycie nieuwierzytelnionej usługi. W tym momencie są one przerywane. Dzieje się tak tylko wtedy, gdy dodatek zostanie opublikowany. Ten sam aktywator w normalnym projekcie Apps Script lub nieopublikowany dodatek jest w ogóle niewykonany, jeśli jakakolwiek część skryptu wymaga autoryzacji.
- Reguły, które można zainstalować, podlegają limitom limitów aktywatorów Apps Script.