Wyzwalacze dotyczące dodatków do edytora

Wyzwalacze Apps Script powodują wykonywanie określonej funkcji skryptu (funkcji aktywatora), gdy wystąpi określone zdarzenie. Tylko określone zdarzenia mogą powodować uruchamianie reguł. Każda aplikacja Google Workspace obsługuje inny zestaw zdarzeń.

Po uruchomieniu reguły zostaje utworzony obiekt zdarzenia. Ta struktura JSON zawiera szczegółowe informacje o zdarzeniu. Informacje w strukturze obiektów zdarzeń są uporządkowane w zależności od typu aktywatora.

Po utworzeniu obiektu zdarzenia Apps Script przekazuje go jako parametr do funkcji aktywatora. Funkcja aktywatora to funkcja wywołania zwrotnego, którą musisz wdrożyć samodzielnie, aby wykonywać działania odpowiednie do reakcji na zdarzenie. Na przykład w dodatku Edytor służy do tworzenia elementów menu dodatków po otwarciu dokumentu. W tym przypadku implementujesz funkcję aktywatora onOpen(e), aby utworzyć potrzebne pozycje menu, korzystając z danych w obiekcie zdarzenia.

Na tej stronie znajdziesz wskazówki dotyczące używania aktywatorów w projektach dodatków do edytora.

Rodzaje aktywatorów dodatku do edytora

W przypadku dodatków do edytora Apps Script możesz korzystać z większości ogólnych typów aktywatorów, w tym z prostych reguł i większości instalacyjnych reguł. Dokładny zestaw dostępnych typów reguł zależy od rozszerzenia aplikacji.

W tabeli poniżej znajdziesz typy prostych i instalacyjnych reguł, których mogą używać dodatki do edycji. Znajdziesz tu też linki do odpowiednich obiektów zdarzeń:

Zdarzenie	Obiekt zdarzenia	Proste aktywatory	Wyzwalacze instalowane
Otwarta Zostanie otwarty plik edytora.	Zdarzenie dotyczące Dokumentów onOpen Zdarzenie dotyczące Formularzy onOpen Obiekt zdarzenia Arkuszy onOpen Obiekt zdarzenia Prezentacji onOpen	Dokumenty Formularze* Arkusze Prezentacje function onOpen(e)	Dokumenty Formularze Arkusze
Zainstaluj Dodatek jest zainstalowany.	Obiekt zdarzenia onInstall	Dokumenty Formularze Arkusze Prezentacje function onInstall(e)
Edytuj Zawartość komórki arkusza kalkulacyjnego została zmieniona.	Obiekt zdarzeń Arkuszy onEdit	Arkusze function onEdit(e)	Arkusze
Zmień Zawartość arkusza jest edytowana lub formatowana.	Obiekt zdarzeń OnChange		Arkusze
Przesłanie formularza Przesłany jest formularz Google.	Obiekt zdarzenia przesłania formularza w formularzu Obiekt zdarzenia przesłania formularza w arkuszu		Formularze Arkusze
Ukierunkowany na czas (zegar) Reguła uruchamia się o określonej godzinie lub w określonym przedziale czasu.	Obiekt zdarzenia na podstawie czasu		Dokumenty Formularze Arkusze Prezentacje

* Zdarzenie otwarte w Formularzach Google nie występuje, gdy użytkownik otwiera formularz, ale aby go zmodyfikować w edytorze.

Proste reguły w dodatkach

Wyzwalacze proste używają skonfigurowanych nazw funkcji, nie mogą korzystać z usług, które wymagają autoryzacji i są automatycznie włączone. W niektórych przypadkach proste zdarzenie aktywatora można obsługiwać za pomocą reguły z możliwością instalacji.

Prosty dodatek do dodatku możesz dodać, implementując funkcję o jednej z tych zarezerwowanych nazw:

• onOpen(e) działa, gdy użytkownik otworzy dokument, arkusz kalkulacyjny lub prezentację. onOpen(e) może też być uruchamiany po otwarciu formularza w edytorze (ale nie podczas odpowiadania na formularz). Jest on wykonywany tylko wtedy, gdy użytkownik ma uprawnienia do edycji danego pliku, i najczęściej jest używany do tworzenia pozycji menu.
• onInstall(e) działa, gdy użytkownik zainstaluje dodatek. Tag onInstall(e) zwykle jest używany do wywołania metody onOpen(e). Dzięki temu menu dodatków pojawiają się natychmiast po instalacji, bez konieczności odświeżania strony przez użytkownika.
• Działanie onEdit(e) jest wykonywane, gdy użytkownik zmienia wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie uruchamia się 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:

• Aktywatory proste nie są uruchamiane, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie). To działanie zapobiega uzupełnianiu menu dodatków.
• W pewnych okolicznościach dodatki do edytora uruchamiają proste aktywatory onOpen(e) i onEdit(e) w trybie bez autoryzacji. Ten tryb wiąże się z dodatkowymi komplikacjami, jak opisano w modelu autoryzacji dodatku.
• Aktywatory proste nie mogą używać usług ani wykonywać innych czynności, które wymagają autoryzacji. Wyjątkiem jest model autoryzacji dodatkowej.
• Reguły proste nie mogą działać dłużej niż 30 sekund. Ogranicz liczbę procesów przetwarzanych do minimum w prostej funkcji aktywatora.
• Proste aktywatory podlegają limitom aktywatora Apps Script.

Reguły do zainstalowania w dodatkach

Dodatki mogą automatycznie tworzyć i modyfikować aktywatory instalowane, korzystając z usługi Apps Script Script. Wyzwalaczy instalowanych dodatków nie można tworzyć ręcznie. W przeciwieństwie do prostych aktywatorów aktywatory możliwe do zainstalowania mogą korzystać z usług, które wymagają autoryzacji.

Reguły, które można zainstalować w dodatkach, nie wysyłają do użytkownika e-maili z błędami, gdy napotkają błędy, ponieważ w większości przypadków użytkownik nie jest w stanie rozwiązać problemu. Dlatego warto zaprojektować dodatek tak, by w miarę możliwości mógł jak najlepiej obsługiwać błędy w imieniu użytkownika.

Dodatki mogą używać tych aktywatorów możliwych do zainstalowania:

• Wystąpienia otwarte, które można zainstalować, są uruchamiane, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub formularz otwierany w edytorze (ale nie podczas odpowiadania na formularz).
• Aktywatory Edytuj są instalowane, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie uruchamia się w odpowiedzi na formatowanie lub inne zmiany, które nie zmieniają wartości komórek.
• Aktywatory zmiany są instalowane, gdy użytkownik wprowadzi jakiekolwiek zmiany w arkuszu kalkulacyjnym, takie jak zmiany formatowania i modyfikacje samego arkusza kalkulacyjnego (np. dodanie wiersza).

• Instalacje możliwe do przesłania za pomocą formularza są wykonywane po przesłaniu odpowiedzi z formularza Google.

• Reguły oparte na czasie (zwane też wyzwalaczami zegara) uruchamiają się o określonej godzinie lub powtarzają się w regularnych odstępach czasu.

Autoryzowanie aktywatorów możliwych do zainstalowania

Standardowo, jeśli deweloper zaktualizuje dodatek, aby używać nowych usług wymagających dodatkowej autoryzacji, zobaczy prośbę o ponowne autoryzowanie dodatku przy następnym użyciu.

Dodatki korzystające z reguł aktywują jednak specjalne testy autoryzacji. Wyobraź sobie dodatek, który używa reguły do monitorowania przesyłania formularzy. Twórca formularza może upoważnić dodatek po pierwszym użyciu, a następnie pozostawić go na kilka miesięcy lub lat, nie otwierając go ponownie. Gdy twórca dodatku będzie musiał zaktualizować dodatek tak, aby używał nowych usług wymagających dodatkowej autoryzacji, twórca formularza nigdy nie zobaczy okna ponownego autoryzacji, ponieważ formularz ponownie nie otworzy się, a dodatek przestanie działać.

W przeciwieństwie do aktywatorów w standardowych projektach Apps Script aktywatory w dodatkach nadal się uruchamiają, nawet jeśli wymagają ponownej autoryzacji. Jeśli jednak natrafisz na wiersz kodu, który wymaga autoryzacji, skrypt nadal będzie kończyć się niepowodzeniem. Aby uniknąć tej sytuacji, deweloperzy mogą użyć metody ScriptApp.getAuthorizationInfo(), aby odblokować dostęp do fragmentów 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 uruchamiających, aby uniknąć problemów z autoryzacją. Przykładowa funkcja aktywatora odpowiada na zdarzenie przesłania formularza w dodatku do Arkuszy Google i, jeśli jest wymagana ponowna autoryzacja, wysyła użytkownikowi dodatku w e-mailu na podstawie alertu HTML.

/**
 * Responds to a form when submitted.
 * @param {event} e The Form submit event.
 */
function respondToFormSubmit(e) {
  const addonTitle = 'My Add-on Title';
  const props = PropertiesService.getDocumentProperties();
  const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);

  // Check if the actions of the trigger requires authorization that has not
  // been granted yet; if so, warn the user via email. This check is required
  // when using triggers with add-ons to maintain functional triggers.
  if (authInfo.getAuthorizationStatus() ===
    ScriptApp.AuthorizationStatus.REQUIRED) {
    // Re-authorization is required. In this case, the user needs to be alerted
    // that they need to re-authorize; the normal trigger action is not
    // conducted, since it requires authorization first. Send at most one
    // "Authorization Required" email per day to avoid spamming users.
    const lastAuthEmailDate = props.getProperty('lastAuthEmailDate');
    const today = new Date().toDateString();
    if (lastAuthEmailDate !== today) {
      if (MailApp.getRemainingDailyQuota() > 0) {
        const html = HtmlService.createTemplateFromFile('AuthorizationEmail');
        html.url = authInfo.getAuthorizationUrl();
        html.addonTitle = addonTitle;
        const message = html.evaluate();
        MailApp.sendEmail(Session.getEffectiveUser().getEmail(),
            'Authorization Required',
            message.getContent(), {
              name: addonTitle,
              htmlBody: message.getContent()
            }
        );
      }
      props.setProperty('lastAuthEmailDate', today);
    }
  } else {
    // Authorization has been granted, so continue to respond to the trigger.
    // Main trigger logic here.
  }
}

<p>The Google Sheets add-on <i><?= addonTitle ?></i> is set to run automatically
    whenever a form is submitted. The add-on was recently updated and it needs you
    to re-authorize it to run on your behalf.</p>

<p>The add-on's automatic functions are temporarily disabled until you
    re-authorize it. To do so, open Google Sheets and run the add-on from the
    Add-ons menu. Alternatively, you can click this link to authorize it:</p>

<p><a href="<?= url ?>">Re-authorize the add-on.</a></p>

<p>This notification email will be sent to you at most once per day until the
    add-on is re-authorized.</p>

Ograniczenia

Reguły do zainstalowania w dodatkach podlegają tym samym ograniczeniom, które regulują uruchamianie aktywatorów w innych typach projektów Apps Script.

Oprócz tych ograniczeń w przypadku dodatków, które można zainstalować w dodatkach, jest kilka ograniczeń:

• Każdy dodatek może mieć tylko 1 regułę każdego typu na użytkownika na dokument. Na przykład w danym arkuszu kalkulacyjnym użytkownik może mieć tylko jedną regułę edycji, ale w tym samym arkuszu kalkulacyjnym może mieć też aktywator przesłania formularza lub regułę opartą na czasie. Inny użytkownik z dostępem do tego samego arkusza kalkulacyjnego może mieć własny oddzielny zestaw reguł.
• Dodatki można tworzyć tylko w przypadku pliku, w którym jest używany dodatek. Oznacza to, że dodatek używany w dokumencie Google A nie może utworzyć aktywatora, który będzie monitorował otwarcie dokumentu Google B.
• Reguły oparte na czasie trwania 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 stanowi wyjątek. To deweloper musi dokładnie sprawdzać przypadki awarii i nimi zarządzać.
• Reguły uruchamiające dodatki przestaną się uruchamiać w tych sytuacjach:
  • Jeśli dodatek zostanie odinstalowany przez użytkownika,
  • Jeśli dodatek zostanie wyłączony w dokumencie (jeśli zostanie ponownie włączony, aktywator ponownie stanie się aktywny) lub
  • Deweloper wycofa publikację dodatku lub prześle jego uszkodzoną wersję do sklepu z dodatkami.
• Funkcje aktywatora dodatku są wykonywane, dopóki nie osiągną kodu, który korzysta z nieautoryzowanej usługi, i w którym momencie je zatrzymuje. Dzieje się tak tylko w przypadku, gdy dodatek zostanie opublikowany; ta sama reguła w zwykłym projekcie Apps Script lub nieopublikowany dodatek w ogóle nie zostanie wykonana, jeśli jakakolwiek część skryptu wymaga autoryzacji.
• Reguły, które można zainstalować, podlegają limitom aktywatora Apps Script.