Reguły dla dodatków do edytora

Aktywatory Apps Script powodują, że określona funkcja skryptu (funkcja aktywatora) jest wykonywana za każdym razem, gdy wystąpi określone zdarzenie. Tylko niektóre zdarzenia mogą powodować uruchamianie wyzwalaczy, a każda aplikacja Google Workspace obsługuje inny zestaw zdarzeń.

Gdy reguła zostanie uruchomiona, tworzony jest obiekt zdarzenia. Ta struktura JSON zawiera szczegóły dotyczące zdarzenia, które miało miejsce. Informacje w strukturze obiektu zdarzenia są uporządkowane w różny sposób w zależności od typu wywołania.

Po utworzeniu obiektu zdarzenia Apps Script przekazuje go jako parametr do funkcji wywołującej. Funkcja wyzwalająca to funkcja wywołania zwrotnego, którą musisz zaimplementować samodzielnie, aby podjąć odpowiednie działania w odpowiedzi na zdarzenie. Na przykład w dodatku do Edytora wyzwalacz służy do tworzenia elementów menu dodatku po otwarciu dokumentu. W takim przypadku implementujesz funkcję wywołującą onOpen(e), aby utworzyć elementy menu potrzebne dodatkowi, być może używając danych z obiektu zdarzenia.

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

Typy reguł dodatków do edytora

W dodatkach do edytora możesz używać większości typów aktywatorów ogólnych dostępnych w projektach Apps Script, w tym prostych aktywatorów i większości aktywatorów z możliwością zainstalowania. Dokładny zestaw dostępnych typów wyzwalaczy zależy od rozszerzanej aplikacji.

W tabeli poniżej znajdziesz typy prostych i instalowanych wyzwalaczy, których mogą używać dodatki do Edytora, oraz linki do odpowiednich obiektów zdarzeń:

Zdarzenie Obiekt zdarzenia Proste aktywatory Reguły możliwe do zainstalowania
Otwórz
 – otworzy się plik edytora.		 Obiekt zdarzenia onOpen w Dokumentach
Obiekt zdarzenia onOpen w Formularzach
Obiekt zdarzenia onOpen w Arkuszach
Obiekt zdarzenia onOpen w Prezentacjach 		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
 Treść komórki arkusza kalkulacyjnego została zmieniona.		 Obiekt zdarzenia onEdit w Arkuszach Arkusze

function onEdit(e)

 Arkusze
Zmiana
 Treść w arkuszu jest edytowana lub formatowana.		 Obiekt zdarzenia onChange w Arkuszach Arkusze
Form-submit
Przesłanie formularza Google.		 Obiekt zdarzenia przesłania formularza w Formularzach
Obiekt zdarzenia przesłania formularza w Arkuszach 		Formularze
Arkusze
Zależne od czasu (zegar)
Wywołanie następuje o określonej godzinie lub w określonym odstępie czasu.		 Obiekt zdarzenia wywoływanego przez czas Dokumenty
Formularze
Arkusze
Prezentacje

* Zdarzenie otwarcia w przypadku Formularzy Google nie występuje, gdy użytkownik otwiera formularz, aby na niego odpowiedzieć, ale gdy edytujący otwiera formularz, aby go zmodyfikować.

Proste aktywatory w dodatkach

Proste wyzwalacze używają zestawu zarezerwowanych nazw funkcji, nie mogą korzystać z usług wymagających autoryzacji i są automatycznie włączane do użycia. W niektórych przypadkach zdarzenie prostego aktywatora może być obsługiwane przez aktywator z możliwością zainstalowania.

Aby dodać prosty wyzwalacz do dodatku, wystarczy zaimplementować funkcję z jedną z tych nazw zastrzeżonych:

  • onOpen(e) jest wykonywana, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub prezentację. onOpen(e) może też być wykonywana, gdy formularz jest otwarty w edytorze (ale nie podczas odpowiadania na formularz). Jest wykonywana tylko wtedy, gdy użytkownik ma uprawnienia do edytowania danego pliku. Najczęściej służy do tworzenia elementów menu.
  • onInstall(e) jest wykonywana, gdy użytkownik zainstaluje dodatek. Zwykle onInstall(e) służy tylko do wywoływania onOpen(e). Dzięki temu menu dodatku pojawiają się natychmiast po instalacji, bez konieczności odświeżania strony przez użytkownika.
  • onEdit(e) jest wykonywana, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ten wyzwalacz nie jest uruchamiany w odpowiedzi na przeniesienie komórki, formatowanie ani inne zmiany, które nie modyfikują wartości komórek.

Ograniczenia

Proste wyzwalacze w dodatkach podlegają tym samym ograniczeniom, które dotyczą prostych wyzwalaczy w innych rodzajach projektów Apps Script. Podczas projektowania dodatków zwróć szczególną uwagę na te ograniczenia:

  • Proste wyzwalacze nie działają, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie). Takie działanie uniemożliwia wypełnienie menu dodatku.
  • W określonych okolicznościach dodatki do Edytora uruchamiają swoje onOpen(e) i onEdit(e) proste reguły w trybie bez autoryzacji. Ten tryb wiąże się z dodatkowymi komplikacjami, które opisano w modelu autoryzacji dodatków.
  • Proste wyzwalacze nie mogą korzystać z usług ani wykonywać innych działań, które wymagają autoryzacji, z wyjątkiem przypadków opisanych w modelu autoryzacji dodatku.
  • Proste wyzwalacze nie mogą działać dłużej niż 30 sekund. Zadbaj o to, aby zminimalizować ilość przetwarzania wykonywanego w funkcji prostego wyzwalacza.
  • Proste aktywatory podlegają limitom aktywatorów Apps Script.

Triggery instalowane w dodatkach

Dodatki mogą programowo tworzyć i modyfikować instalowane reguły za pomocą usługi Apps Script Script. Instalowanych reguł dodatku nie można tworzyć ręcznie. W przeciwieństwie do prostych wyzwalaczy wyzwalacze instalowane mogą korzystać z usług wymagających autoryzacji.

Triggery instalowane w dodatkach nie wysyłają do użytkownika e-maili z informacjami o błędach, ponieważ w większości przypadków użytkownik nie jest w stanie rozwiązać problemu. Dlatego w miarę możliwości zaprojektuj dodatek tak, aby w imieniu użytkownika radził sobie z błędami.

Dodatki mogą korzystać z tych wywołań instalowanych:

  • Otwórz wywoływacze instalowane są wykonywane, gdy użytkownik otwiera dokument lub arkusz kalkulacyjny albo gdy formularz jest otwierany w edytorze (ale nie podczas odpowiadania na formularz).
  • Edytowanie wywoływaczy instalowanych jest wykonywane, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ten wyzwalacz nie jest aktywowany w odpowiedzi na formatowanie ani inne zmiany, które nie modyfikują wartości komórek.
  • Zmień wywoływacze instalowane są uruchamiane, gdy użytkownik wprowadzi dowolną zmianę w arkuszu kalkulacyjnym, w tym zmiany formatowania i modyfikacje samego arkusza (np. dodanie wiersza).

  • Triggery instalowane typu „Form-submit” są uruchamiane po przesłaniu odpowiedzi w Formularzach Google.

  • Wyzwalacze czasowe (nazywane też wyzwalaczami zegarowymi) uruchamiają się o określonej godzinie lub wielokrotnie w regularnych odstępach czasu.

Autoryzowanie aktywatorów, które można zainstalować

Zwykle, jeśli deweloper zaktualizuje dodatek, aby korzystał z nowych usług wymagających dodatkowej autoryzacji, użytkownicy są proszeni o ponowne autoryzowanie dodatku przy następnym użyciu.

Jednak dodatki, które korzystają z wyzwalaczy, napotykają specjalne problemy z autoryzacją. Wyobraź sobie dodatek, który używa wyzwalacza do monitorowania przesyłania formularzy: twórca formularza może autoryzować dodatek przy pierwszym użyciu, a następnie pozostawić go do działania przez miesiące lub lata bez ponownego otwierania formularza. Jeśli deweloper dodatku zaktualizuje go, aby korzystał z nowych usług, które wymagają dodatkowej autoryzacji, twórca formularza nigdy nie zobaczy okna ponownej autoryzacji, ponieważ nie otworzy ponownie formularza, a dodatek przestanie działać.

W przeciwieństwie do wyzwalaczy w zwykłych projektach Apps Script wyzwalacze w dodatkach są uruchamiane nawet wtedy, gdy wymagają ponownej autoryzacji. Jeśli jednak skrypt napotka wiersz kodu, który wymaga autoryzacji, której nie ma, nadal nie będzie działać. Aby uniknąć takiej sytuacji, deweloperzy mogą użyć metody ScriptApp.getAuthorizationInfo() do ograniczenia dostępu do części kodu, które uległy zmianie między opublikowanymi wersjami dodatku.

Poniżej znajdziesz przykład zalecanej struktury funkcji wyzwalających, która pozwala uniknąć problemów z autoryzacją. Przykładowa funkcja wyzwalacza reaguje na zdarzenie przesłania formularza w dodatku do Arkuszy Google i w razie potrzeby ponownej autoryzacji wysyła do użytkownika dodatku e-mail z alertem przy użyciu szablonu HTML.

Code.gs

triggers/form/Code.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.
  }
}

authorizationemail.html

triggers/form/AuthorizationEmail.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

Triggery instalowane w dodatkach podlegają tym samym ograniczeniom, które obowiązują w przypadku triggerów instalowanych w innych rodzajach projektów Apps Script.

Oprócz tych ograniczeń w przypadku instalowanych wyzwalaczy w dodatkach obowiązuje kilka dodatkowych ograniczeń:

  • Każdy dodatek może mieć tylko 1 wyzwalacz danego typu na użytkownika i dokument. Na przykład w danym arkuszu kalkulacyjnym użytkownik może mieć tylko jeden wyzwalacz edycji, ale może też mieć w tym samym arkuszu wyzwalacz przesyłania formularza lub wyzwalacz oparty na czasie. Inny użytkownik z dostępem do tego samego arkusza kalkulacyjnego może mieć własny, oddzielny zestaw reguł.
  • Dodatki mogą tworzyć wyzwalacze tylko w pliku, w którym są używane. Oznacza to, że dodatek używany w Dokumencie Google A nie może utworzyć czynnika uruchamiającego, który będzie monitorować otwieranie Dokumentu Google B.
  • Triggery oparte na czasie nie mogą być uruchamiane częściej niż raz na godzinę.
  • Dodatki nie wysyłają automatycznie e-maili do użytkowników, gdy kod uruchamiany przez wywoływacz instalacyjny zgłasza wyjątek. Programista musi sprawdzić i odpowiednio obsłużyć przypadki niepowodzenia.
  • Aktywatory dodatków przestają się uruchamiać w tych sytuacjach:
    • Jeśli dodatek zostanie odinstalowany przez użytkownika,
    • jeśli dodatek jest wyłączony w dokumencie (po ponownym włączeniu wyzwalacz znów zacznie działać);
    • Jeśli deweloper wycofa dodatek z publikacji lub prześle do sklepu z dodatkami uszkodzoną wersję.
  • Funkcje aktywatorów dodatków są wykonywane do momentu, gdy napotkają kod korzystający z nieautoryzowanej usługi. W tym momencie ich działanie zostaje przerwane. Dzieje się tak tylko wtedy, gdy dodatek jest opublikowany. Ten sam wyzwalacz w zwykłym projekcie Apps Script lub nieopublikowanym dodatku nie jest w ogóle wykonywany, jeśli jakakolwiek część skryptu wymaga autoryzacji.
  • Triggery instalowane podlegają limitom triggerów Apps Script.