Wyzwalacze dotyczące dodatków do edytora

Wyzwalacze Apps Script powodują wykonanie określonej funkcji skryptu (funkcji aktywatora) po wystąpieniu określonego zdarzenia. Tylko niektóre zdarzenia mogą powodować uruchamianie aktywatorów, a każda aplikacja Google Workspace obsługuje inny zestaw zdarzeń.

Uruchomienie reguły powoduje utworzenie obiektu zdarzenia. Ta struktura JSON zawiera szczegółowe informacje o wystąpieniu zdarzenia. Informacje w strukturze obiektu zdarzenia są uporządkowane w różny sposób 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 potrzebne do odpowiedzi na zdarzenie. Na przykład dodatek do edytora służy do tworzenia pozycji menu dodatków po otwarciu dokumentu. W tym przypadku zaimplementujesz funkcję aktywatora onOpen(e), aby utworzyć pozycje menu, których potrzebuje dodatek, prawdopodobnie z użyciem danych w obiekcie zdarzenia.

Na tej stronie znajdziesz wskazówki dotyczące korzystania z aktywatorów w projektach dodatków do edycji.

Typy aktywatorów dodatku do Edytora

Możesz używać większości ogólnych typów aktywatorów dostępnych dla projektów Apps Script w dodatkach do Edytora, w tym prostych aktywatorów i większości reguł możliwych do zainstalowania. Dokładny zestaw dostępnych typów aktywatorów zależy od rozszerzonej aplikacji.

W tabeli poniżej znajdziesz typy prostych i możliwych do zainstalowania aktywatorów, z których mogą korzystać dodatki do Edytora, a także linki do odpowiednich obiektów zdarzeń:

Zdarzenie Obiekt zdarzenia Proste reguły Aktywatory do zainstalowania
Otwórz
Otwarto plik edytora.
Obiekt zdarzenia Dokumenty onOpen
Obiekt zdarzenia Formularze onOpen
Obiekt zdarzenia w Arkuszach onOpen
Obiekt zdarzenia Prezentacji Google
Dokumenty
Formularze*
Arkusze
Prezentacje

function onOpen(e)

Dokumenty
Formularze
Arkusze
Zainstaluj
Dodatek zostanie zainstalowany.
Obiekt zdarzenia onInstall Dokumenty
Formularze
Arkusze
Prezentacje

function onInstall(e)

Edytuj
Zawartość komórki arkusza kalkulacyjnego uległa zmianie.
Arkusze onEdit obiekt zdarzenia Arkusze

function onEdit(e)

Arkusze
Zmiana
Zawartość arkusza jest edytowana lub sformatowana.
Obiekt zdarzenia w Arkuszach onChange Arkusze
Przesłanie formularza
Przesyłany jest formularz Google.
Obiekt zdarzenia Form-submit w Formularzach
Obiekt zdarzenia formularza przesyłania formularzy
Formularze
Arkusze
Na podstawie czasu (zegar)
Reguła uruchamia się w określonym czasie lub w określonym przedziale czasu.
Obiekt zdarzenia zależnego od czasu Dokumenty
Formularze
Arkusze
Prezentacje

* Zdarzenie „otwarty” w Formularzach Google nie następuje wtedy, gdy użytkownik otworzy formularz, by odpowiedzieć, ale gdy edytor otworzy formularz w celu wprowadzenia w nim zmian.

Proste reguły w dodatkach

Proste aktywatory używają zestawu zastrzeżonych nazw funkcji, nie mogą korzystać z usług wymagających autoryzacji i są automatycznie włączane do użycia. W niektórych przypadkach proste zdarzenie aktywatora może być obsługiwane przez aktywator, który można zainstalować.

Prosty aktywator możesz dodać do dodatku, implementując funkcję z jedną z tych zarezerwowanych nazw:

  • onOpen(e) uruchamia się, 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 edytowania danego pliku, i najczęściej służy do tworzenia elementów menu.
  • onInstall(e) jest uruchamiany, gdy użytkownik zainstaluje dodatek. Zwykle onInstall(e) służy do wywołania onOpen(e). Dzięki temu menu dodatków pojawi się od razu po instalacji, bez potrzeby odświeżania strony przez użytkownika.
  • Funkcja onEdit(e) jest uruchamiana, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie uruchamia się w odpowiedzi na przesunięcia komórek, formatowanie lub inne zmiany, które nie powodują zmiany wartości komórki.

Ograniczenia

Proste aktywatory w dodatkach podlegają tym samym ograniczeniom, które regulują proste reguły w innych rodzajach projektów Apps Script. Podczas projektowania dodatków zwróć uwagę na te ograniczenia:

  • Proste aktywatory nie działają, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlania lub komentarza). Takie zachowanie zapobiega wypełnianiu menu dodatków.
  • W pewnych okolicznościach dodatki do Edytora uruchamiają proste reguły onOpen(e) i onEdit(e) w trybie braku autoryzacji. Ten tryb wiąże się z dodatkowymi komplikacjami, zgodnie z opisem w modelu autoryzacji dodatków.
  • Aktywatory proste nie mogą używać usług ani wykonywać innych działań wymagających autoryzacji, z wyjątkiem sytuacji opisanych w modelu autoryzacji dodatków.
  • Proste aktywatory nie mogą działać dłużej niż 30 sekund. Zadbaj o to, by zminimalizować ilość przetwarzania wykonywanego w prostej funkcji aktywatora.
  • Proste aktywatory podlegają limitom aktywatorów Apps Script.

Aktywatory instalowane w dodatkach

Dodatki mogą programowo tworzyć i modyfikować aktywatory instalowane za pomocą usługi Apps Script Script. Aktywatorów, które można zainstalować, nie można tworzyć ręcznie. W przeciwieństwie do prostych aktywatorów aktywatory do zainstalowania mogą korzystać z usług, które wymagają autoryzacji.

Aktywatory do zainstalowania w dodatkach nie wysyłają e-maili o błędach do użytkownika, gdy napotka on błędy, ponieważ w większości przypadków użytkownik nie jest w stanie rozwiązać problemu. Dlatego warto zaprojektować dodatek w taki sposób, aby w miarę możliwości usuwał błędy w imieniu użytkownika.

Dodatki mogą używać tych wyzwalaczy do zainstalowania:

  • Aktywatory Otwórz, które można zainstalować, są wykonywane, gdy użytkownik otworzy dokument lub arkusz kalkulacyjny albo gdy formularz zostanie otwarty w edytorze (ale nie po otwarciu formularza).
  • Aktywatory do zainstalowania są Edytowalne, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ten aktywator nie uruchamia się w odpowiedzi na zmiany formatowania ani inne zmiany, które nie powodują zmiany wartości w komórkach.
  • Aktywatory zmiany, które można zainstalować, są wykonywane, gdy użytkownik wprowadzi zmiany w arkuszu kalkulacyjnym, w tym zmiany formatowania i zmiany samego arkusza kalkulacyjnego (np. dodanie wiersza).
  • Aktywatory przesłania formularza są uruchamiane po przesłaniu odpowiedzi formularza Google.

  • Aktywatory zależne od czasu (nazywane też regułami zegara) uruchamiają się o określonej godzinie lub wielokrotnie w regularnych odstępach czasu.

Autoryzowanie aktywatorów do zainstalowania

Zwykle, gdy deweloper zaktualizuje dodatek, aby używał nowych usług, które wymagają dodatkowej autoryzacji, użytkownicy są proszeni o ponowną autoryzację tego dodatku przy następnym jego użyciu.

Jednak w przypadku dodatków, które używają aktywatorów, występują szczególne problemy z autoryzacją. Wyobraźmy sobie dodatek wykorzystujący regułę do monitorowania przesłanych formularzy: twórca formularzy mógł autoryzować ten dodatek przy pierwszym użyciu tego dodatku, a następnie pozostawić go aktywny przez miesiące lub lata i nigdy nie otwierać formularza. Gdyby deweloper dodatku zaktualizował dodatek, aby używał nowych usług, które wymagają dodatkowej autoryzacji, twórca formularza nigdy nie zobaczy okna ponownej autoryzacji, ponieważ nigdy nie otworzył formularza, a dodatek przestanie działać.

W przeciwieństwie do aktywatorów w standardowych projektach Apps Script, aktywatory w dodatkach działają nawet wtedy, gdy wymagają ponownej autoryzacji. Skrypt nadal nie działa, jeśli trafi w wiersz kodu wymagającego autoryzacji, której nie ma skrypt. Aby uniknąć takiej sytuacji, deweloperzy mogą za pomocą metody ScriptApp.getAuthorizationInfo() zablokować dostęp do tych części kodu, które zmieniły się w poszczególnych opublikowanych wersjach dodatku.

Poniżej znajdziesz przykład zalecanej struktury do użycia w funkcjach aktywują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 ponowna autoryzacja jest wymagana, wysyła użytkownikowi dodatku e-maila z alertem za pomocą szablonu HTML.

Code.gs

aktywatory/formularz/kod.gs
/**
 * 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.
  }
}

e-mail autoryzacji.html

aktywatory/formularz/E-mail autoryzacji.html
<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

Aktywatory do zainstalowania w dodatkach podlegają tym samym ograniczeniom, które regulują aktywatory możliwe do zainstalowania w innych rodzajach projektów Apps Script.

Oprócz tych ograniczeń w przypadku reguł, które można zainstalować, obowiązują pewne ograniczenia:

  • Każdy dodatek może mieć tylko 1 regułę danego typu na użytkownika w danym dokumencie. Na przykład w danym arkuszu kalkulacyjnym dany użytkownik może mieć tylko jedną regułę edycji, chociaż może on również obejmować regułę przesłania formularza lub regułę czasu. 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 Google A nie może utworzyć reguły monitorowania po otwarciu dokumentu Google B.
  • Reguły zależne od czasu nie mogą być uruchamiane częściej niż raz na godzinę.
  • Dodatki nie wysyłają automatycznie e-maila do użytkownika, gdy kod uruchamiany przez aktywator, który można zainstalować, powoduje zgłoszenie wyjątku. To deweloper spoczywa na deweloperze, aby sprawnie wykrywać przypadki niepowodzenia i radzić sobie z nimi.
  • Reguły dodatków przestają się uruchamiać w następujących sytuacjach:
    • Jeśli dodatek zostanie odinstalowany przez użytkownika,
    • jeśli dodatek zostanie wyłączony w dokumencie (jeśli zostanie ponownie włączony, aktywator znów zacznie działać).
    • deweloper wycofa publikację dodatku lub prześle jego niedziałającą wersję do sklepu z dodatkami.
  • Dodatkowe funkcje aktywujące są wykonywane, dopóki nie dotrą do kodu korzystającego z nieautoryzowanej usługi, co zatrzymuje działanie. Dzieje się tak tylko wtedy, gdy dodatek jest opublikowany. Ten sam aktywator w zwykłym projekcie Apps Script lub nieopublikowany dodatek nie jest uruchamiany, jeśli jakakolwiek część skryptu wymaga autoryzacji.
  • Aktywatory, które można zainstalować, podlegają limitom aktywatora Apps Script.