Wyzwalacze Apps Script powodują wystąpienie określonego skryptu funkcja (funkcja wyzwalacza), która ma być wykonywana za każdym razem, gdy określone zdarzenie ma miejsce. Tylko niektóre zdarzenia mogą powodować uruchamianie reguł. Aplikacja Google Workspace obsługuje inny zestaw zdarzeń.
Po uruchomieniu reguły tworzony jest obiekt zdarzenia. Ta struktura JSON zawiera szczegółowe informacje o wystąpieniu zdarzenia. Informacje zawarte w zdarzeniu czy struktura obiektu jest różna w zależności od typu reguły.
Po utworzeniu obiektu zdarzenia Apps Script przekazuje go jako parametr do
. Funkcja aktywatora to funkcja wywołania zwrotnego,
wdrożenia i działań, które pozwolą
zareagować
. Na przykład w wyzwalaczu dodatku edytora
służy do tworzenia pozycji menu dodatkowych po otwarciu dokumentu. W tym przypadku
zaimplementuj w funkcji aktywatora onOpen(e)
, aby utworzyć pozycje menu dodatku
używając danych z obiektu zdarzenia.
Na tej stronie znajdziesz wytyczne dotyczące używania reguł w edytujący projektów dodatkowych.
Typy aktywatorów dodatków do edytora
Możesz używać większości ogólnych typów aktywatorów dostępnych w projektach Apps Script w dodatkach do Edytora, w tym prostych aktywatorów. i większości reguł, które można zainstalować. dokładny zestaw dostępnych typów aktywatorów zależy od rozszerzenia aplikacji.
W tabeli poniżej znajdziesz typy prostych i możliwych do zainstalowania aktywatorów, które Dodatki do edytora, z których mogą korzystać, i dostarczają linki do odpowiednich obiektów zdarzeń:
Zdarzenie | Obiekt zdarzenia | Proste aktywatory | Aktywatory instalacyjne |
---|---|---|---|
Otwórz Otwarto plik edytora. |
Dokumenty onOpen obiekt zdarzenia . Obiekty wydarzenia Formularzy onOpen Arkusze onOpen obiekt zdarzenia , Obiekty zdarzeń w Prezentacjach onOpen |
![]() ![]() ![]() ![]()
|
![]() ![]() ![]() |
Zainstaluj Dodatek jest zainstalowany. |
obiekt zdarzenia onInstall |
![]() ![]() ![]() ![]()
|
|
Edytuj Zawartość komórki arkusza kalkulacyjnego została zmieniona. |
Obiekt zdarzenia onEdit |
![]()
|
![]() |
Zmiana Zawartość arkusza została zmodyfikowana lub sformatowana. |
Obiekt zdarzenia Arkuszy onChange |
![]() |
|
Przesłanie formularza Formularz Google został przesłany. |
Obiekt zdarzenia przesłania formularza w Formularzach . Obiekt zdarzenia przesłania formularza w Arkuszach |
![]() ![]() |
|
Ograniczony czasowo (zegar) Reguła uruchamia się w określonym czasie lub w określonym przedziale czasu. |
Obiekt zdarzenia zależnego od czasu |
![]() ![]() ![]() ![]() |
* Otwarte zdarzenie w Formularzach Google nie występuje, gdy użytkownik otworzy , a nie wtedy, gdy edytujący otworzy formularz, aby go zmodyfikować.
Proste aktywatory w dodatkach
Proste aktywatory używają zbioru zarezerwowanego. nie mogą używać usług wymagających autoryzacji oraz automatycznie włączone do użytku. W niektórych przypadkach proste zdarzenie aktywujące może będzie obsługiwana przez wyzwalacz z możliwością zainstalowania.
Aby dodać prosty aktywator do dodatku, zaimplementuj funkcję z jedną z tych zarezerwowanych nazw:
onOpen(e)
działa, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub prezentacji. KodonOpen(e)
może być także wykonywany po otwarciu formularza w edytorze (ale nie podczas odpowiadania na formularz). Wykonywane jest tylko wtedy, gdy użytkownik uprawnień do edycji danego pliku. Są najczęściej używane do tworzenia pozycje menu.- Działanie
onInstall(e)
jest wykonywane, gdy użytkownik zainstaluje dodatek. ZwykleonInstall(e)
jest tylko używany do wywoływania funkcjionOpen(e)
; Dzięki temu menu dodatków będzie widoczne natychmiast po instalacji bez konieczności odświeżania strony przez użytkownika. - Pole
onEdit(e)
jest wykonywane, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie uruchamia się w odpowiedzi na przeniesienie komórki, formatowanie lub inne zmiany, które nie powodują zmiany wartości w komórkach.
Ograniczenia
Proste aktywatory w dodatkach podlegają tym samym ograniczeń dotyczących prostych elementów aktywatory w innych rodzajach projektów Apps Script. Zwróć uwagę na te kwestie ograniczeń przy projektowaniu dodatków:
- Proste aktywatory nie działają, jeśli plik jest otwarty tylko do odczytu (wyświetl lub ). Takie działanie uniemożliwia wypełnianie menu dodatków.
- W pewnych okolicznościach dodatki do Edytora Google Ads uruchamiają tagi
onOpen(e)
orazonEdit(e)
prostych aktywatorów w trybie bez autoryzacji. Ten tryb przedstawia komplikacje opisane w . - Proste aktywatory nie mogą używać usług ani podejmować inne działania, które wymagają autoryzacji, z wyjątkiem opisane w model autoryzacji dodatków.
- Proste reguły nie mogą działać dłużej niż 30 sekund. Postaraj się zminimalizować ilość przetwarzania wykonanego przez prostą funkcję wyzwalacza.
- Proste aktywatory podlegają aktywatorowi Apps Script limity.
Wyzwalacze do zainstalowania w dodatkach
Dodatki mogą
automatyczne tworzenie i modyfikowanie reguł możliwych do zainstalowania.
przy użyciu usługi Apps Script Script
. dodatek
aktywatorów możliwych do zainstalowania nie można tworzyć ręcznie. W przeciwieństwie do prostych reguł
Aktywatory możliwe do zainstalowania mogą używać usług, które wymagają autoryzacji.
Aktywatory możliwe do zainstalowania w dodatkach nie wysyłają e-maili o błędach. użytkownikom, którzy napotkają błędy, ponieważ w większości przypadków aby rozwiązać problem. Z tego powodu dodatek powinien być płynnie obsługiwać błędy w imieniu użytkownika, gdy tylko jest to możliwe.
Dodatki mogą używać tych aktywatorów, które można zainstalować:
- Otwarte reguły z możliwością zainstalowania są uruchamiane, gdy użytkownik otworzy dokument. arkusza kalkulacyjnego lub po otwarciu formularza w edytorze (ale nie podczas do formularza).
- Edytuj reguły instalacyjne są wykonywane, gdy użytkownik zmieni wartość komórki w arkusz kalkulacyjny. Ta reguła nie uruchamia się w odpowiedzi na formatowanie lub inne zmiany, które nie zmieniają wartości komórek.
- Zmiana uruchamianych reguł uruchamiających się jest wykonywana, gdy użytkownik wprowadzi arkusza kalkulacyjnego, w tym zmian formatowania i modyfikacji; (np. dodanie wiersza).
Instalacyjne reguły związane z przesłaniem formularza są uruchamiane, gdy odpowiedź w Formularzu Google jest przesłano.
Reguły oparte na czasie (nazywane również aktywatorami zegara) uruchamiają się o określonej godzinie lub wielokrotnie na w regularnych odstępach czasu.
Autoryzacja aktywatorów możliwych do zainstalowania
Zwykle, jeśli deweloper zaktualizuje dodatek, aby używał nowych usług, które wymagają w celu przeprowadzenia dodatkowej autoryzacji, użytkownik zostanie poproszony o ponowną autoryzację dodatku za każdym razem, gdy z niej korzystają.
Jednak dodatki korzystające z aktywatorów podlegają specjalnym testom autoryzacyjnym. Wyobraź sobie dodatek, który używa aktywatora do monitorowania przesłanych formularzy: formularza twórca może autoryzować dodatek przy pierwszym użyciu, a potem pozostawić go mogą działać przez miesiące lub lata bez ponownego otwierania formularza. Jeśli programista dodatku zaktualizował dodatek, aby używał nowych usług, które wymaga dodatkowej autoryzacji, twórca nigdy nie zobaczy formularza okna ponownej autoryzacji, ponieważ formularz i dodatek nigdy nie został ponownie otwarty. przestanie działać.
W przeciwieństwie do aktywatorów w zwykłych projektach Apps Script, wyzwalacze w
są nadal uruchamiane, nawet jeśli wymagają ponownej autoryzacji. Jednak skrypt
nadal kończy się niepowodzeniem, jeśli trafi na wiersz kodu, który wymaga autoryzacji skryptu
których nie ma. Aby uniknąć takiej sytuacji, deweloperzy mogą użyć metody
ScriptApp.getAuthorizationInfo()
do części kodu, które uległy zmianie między opublikowanymi wersjami
po zainstalowaniu dodatku.
Poniżej znajduje się przykład zalecanej struktury do użycia w funkcjach aktywujących uniknąć pułapek z autoryzacją. Przykładowa funkcja aktywatora odpowiada na typu „formularz” w dodatku do Arkuszy Google, a w przypadku wysyła do użytkownika dodatku e-mail z alertem przy użyciu szablonu HTML.
Code.gs
authorizationemail.html
Ograniczenia
Aktywatory instalacyjne w dodatkach podlegają tym samym ograniczenia które regulują aktywatory instalacyjne w innych rodzajach projektów Apps Script.
Oprócz tych ograniczeń obowiązują też pewne ograniczenia dotyczące w szczególności:
- Każdy dodatek może mieć tylko 1 wyzwalacz danego typu na użytkownika na dokument. Na przykład w danym arkuszu kalkulacyjnym dany użytkownik może mieć tylko jedną zmianę. chociaż użytkownik może mieć również regułę opartą na przesłaniu formularza w tym samym arkuszu kalkulacyjnym dla reguł opartych na czasie. Inny użytkownik z dostępem do tego samego arkusza kalkulacyjnego może mieć własny zestaw reguł.
- Dodatki mogą tworzyć aktywatory tylko dla pliku, w którym jest on używany. Oznacza to, że dodatek używany w dokumencie A Google nie może utworzyć reguły do sprawdzanie, kiedy jest otwarty dokument Google B.
- Reguły oparte na czasie nie mogą być uruchamiane częściej niż raz na godzinę.
- Dodatki nie wysyłają automatycznie e-maila do użytkownika, gdy kod uruchamia się instalacyjny aktywator zgłasza wyjątek. Sprawdzanie zależy od dewelopera i odpowiednio radzić sobie z przypadkami awarii.
- Aktywatory dodatków przestają się uruchamiać w tych sytuacjach:
- Jeśli użytkownik odinstaluje dodatek:
- Jeśli dodatek jest wyłączony w dokumencie (po ponownym włączeniu, czynnik uruchamiający ponownie funkcjonuje) lub
- Jeśli deweloper cofnie publikację dodatku lub prześle jego niedziałającą wersję do w sklepie z dodatkami.
- Dodatkowe funkcje aktywatora są wykonywane, dopóki nie dotrą do kodu, który używa nieautoryzowana usługa, w którym usługa zostanie zatrzymana. Dzieje się tak tylko wtedy, gdy dodatek został opublikowany; ten sam aktywator w zwykłym projekcie Apps Script lub nieopublikowany dodatek w ogóle nie działa, jeśli jakakolwiek część skryptu wymaga autoryzacji.
- Aktywatory możliwe do zainstalowania podlegają aktywatorowi Apps Script limity.