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ółowe informacje o zdarzeniu, 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 ogólnych typów wyzwalaczy dostępnych w projektach Google Apps Script, w tym prostych wyzwalaczy i większości wyzwalaczy instalowanych. Dokładny zestaw dostępnych typów wyzwalaczy zależy od rozszerzanej aplikacji.

W przeciwieństwie do dodatków do edytorów dodatki do Google Workspace nie mogą używać ogólnych prostych ani instalowanych wyzwalaczy Apps Script. Zamiast tego używają reguł zaprojektowanych specjalnie dla dodatków do Google Workspace. Więcej informacji znajdziesz w artykule Triggery dodatków do Google Workspace.

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

Zdarzenie	Obiekt zdarzenia	Proste aktywatory	Wyzwalacze, które można zainstalować
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ć do dodatku prosty aktywator, zaimplementuj funkcję o jednej z tych nazw zastrzeżonych:

• onOpen jest wykonywana, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub prezentację. onOpen może też być wykonywana, gdy formularz jest otwierany 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 jest wykonywana, gdy użytkownik zainstaluje dodatek. Zwykle onInstall służy tylko do wywoływania funkcji onOpen. Dzięki temu menu dodatku pojawiają się natychmiast po instalacji bez konieczności odświeżania strony przez użytkownika.
• onEdit jest wykonywana, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ten wyzwalacz nie jest aktywowany w odpowiedzi na przeniesienie komórek, 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). Uniemożliwia to wypełnianie menu dodatku.
• W określonych sytuacjach dodatki do Edytora uruchamiają swoje onOpen i onEdit proste reguły w trybie bez autoryzacji. Ten tryb przedstawia komplikacje opisane 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. Zminimalizuj 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 wyzwalacze za pomocą usługi Apps Script Script. Instalowanych wyzwalaczy dodatków nie można tworzyć ręcznie. W odróżnieniu od prostych wyzwalaczy wyzwalacze instalowane mogą korzystać z usług, które wymagają autoryzacji.

Triggery instalowane w dodatkach nie wysyłają do użytkownika e-maili z informacją o błędach, ponieważ w większości przypadków użytkownik nie może rozwiązać problemu. Dlatego w miarę możliwości projektuj dodatek tak, aby w imieniu użytkownika elegancko obsługiwał błędy.

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

• Otwórz wywoływane przez instalację uruchamiają się, gdy użytkownik otwiera dokument lub arkusz kalkulacyjny albo gdy formularz jest otwierany w edytorze (ale nie podczas odpowiadania na formularz).
• Edytowanie instalowalnych aktywatorów 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 Form-submit są uruchamiane po przesłaniu odpowiedzi w Formularzach Google.

  Istnieją 2 wersje wyzwalaczy przesyłania formularza: jedna dla Arkuszy (w których zbierane są odpowiedzi na formularz) i jedna dla Formularzy Google. Obiekt zdarzenia przekazywany do funkcji wywoływanej przez wyzwalacz przesyłania formularza w Arkuszach jest prostszy i zwraca wartości odpowiedzi w prostych tablicach. Obiekt zdarzenia przekazywany do funkcji wyzwalanej przez przesłanie formularza w Formularzach zawiera więcej informacji w obiekcie FormResponse.

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

Autoryzowanie aktywatorów instalowanych

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 wymagających 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. Skrypt nadal jednak nie działa, jeśli napotka wiersz kodu, który wymaga autoryzacji, której nie ma. Aby tego uniknąć, użyj ScriptApp.getAuthorizationInfo do ograniczenia dostępu do części kodu, które uległy zmianie między wersjami dodatku.

Poniższe przykłady pokazują zalecaną strukturę funkcji wyzwalacza, 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 w formacie 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

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ć 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 wyzwalaczy.
• Dodatki mogą tworzyć wyzwalacze tylko dla pliku, w którym są używane. Oznacza to, że dodatek używany w Dokumencie Google A nie może utworzyć wyzwalacza, który będzie monitorować otwieranie Dokumentu Google B.
• Triggery oparte na czasie nie mogą być uruchamiane częściej niż raz na godzinę.
• Gdy kod uruchomiony przez wywoływacz instalacyjny zgłosi wyjątek, dodatki nie wysyłają automatycznie e-maila do użytkownika. Deweloper musi sprawdzać i obsługiwać przypadki niepowodzenia.
• Reguły uruchamiające 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 aktywator znów zacznie działać);
  • Jeśli deweloper wycofa dodatek z publikacji lub prześle do sklepu z dodatkami uszkodzoną wersję.
• Funkcje aktywatora dodatku są wykonywane do momentu, w którym osiągną kod korzystający z nieautoryzowanej usługi. Wtedy się zatrzymują. Jest to prawda 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.