Reguły dla dodatków do edytora

Reguły Apps Script powodują, że określona funkcja skryptu (tzw. funkcja reguły) jest wykonywana za każdym razem, gdy wystąpi określone zdarzenie . Tylko niektóre zdarzenia mogą powodować uruchamianie reguł, 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 wystąpiło. Informacje w strukturze obiektu zdarzenia są uporządkowane inaczej w zależności od typu reguły.

Po utworzeniu obiektu zdarzenia Apps Script przekazuje go jako parametr do funkcji reguły. Funkcja reguły 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 reguła służy do tworzenia elementów menu dodatku po otwarciu dokumentu. W takim przypadku implementujesz funkcję reguły onOpen(e), aby utworzyć elementy menu potrzebne dodatkowi, ewentualnie 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 reguł dostępnych w projektach Google Apps Script, w tym prostych reguł i większości reguł instalowanych. Dokładny zestaw dostępnych typów reguł zależy od rozszerzanej aplikacji.

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

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

Zdarzenie	Obiekt zdarzenia	Proste reguły	Aktywatory instalowalne
Otwórz Otwierany jest 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 jest instalowany.	Obiekt zdarzenia onInstall	Dokumenty Formularze Arkusze Prezentacje function onInstall(e)
Edytuj Zmieniana jest zawartość komórki arkusza kalkulacyjnego.	Obiekt zdarzenia onEdit w Arkuszach	Arkusze function onEdit(e)	Arkusze
Zmień Treść w arkuszu jest edytowana lub formatowana.	Obiekt zdarzenia onChange w Arkuszach		Arkusze
Prześlij formularz Przesyłany jest formularz Google.	Obiekt zdarzenia form-submit w Formularzach Obiekt zdarzenia form-submit w Arkuszach		Formularze Arkusze
Zależne od czasu (zegar) Reguła jest uruchamiana o określonej godzinie lub w określonym odstępie czasu.	Obiekt zdarzenia zależnego od czasu	Dokumenty Formularze Arkusze Prezentacje

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

Proste reguły w dodatkach

Proste reguły 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 proste zdarzenie wyzwalające może być obsługiwane przez wyzwalacz instalowalny.

Aby dodać prostą regułę do dodatku, zaimplementuj funkcję o jednej z tych zarezerwowanych nazw:

• onOpen jest wykonywana, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub prezentację. onOpen może być też 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, i najczęściej służy do tworzenia elementów menu.
• onInstall jest wykonywana, gdy użytkownik instaluje dodatek. Zwykle onInstall służy tylko do wywoływania 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 zmienia wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie jest uruchamiana w odpowiedzi na przenoszenie komórek, formatowanie ani inne zmiany, które nie zmieniają wartości komórek.

Ograniczenia

Proste reguły w dodatkach podlegają tym samym ograniczeniom, które obowiązują w przypadku prostych reguł w innych rodzajach projektów Apps Script. Podczas projektowania dodatków zwróć szczególną uwagę na te ograniczenia:

• Proste reguły nie są uruchamiane, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlania lub komentowania). To zachowanie uniemożliwia wypełnianie menu dodatku.
• W pewnych okolicznościach dodatki do edytora uruchamiają proste reguły onOpen i onEdit w trybie bez autoryzacji. Ten tryb powoduje komplikacje opisane w modelu autoryzacji dodatku.
• Proste reguły nie mogą korzystać z usług ani wykonywać innych działań wymagających autoryzacji, z wyjątkiem przypadków opisanych w modelu autoryzacji dodatku.
• Proste reguły nie mogą działać dłużej niż 30 sekund. Zminimalizuj ilość przetwarzania wykonywanego w funkcji prostej reguły.
• Proste reguły podlegają limitom przydziału reguł Apps Script .

Reguły instalowane w dodatkach

Dodatki mogą programowo tworzyć i modyfikować reguły instalowane za pomocą usługi Apps Script Script. Reguł instalowanych w dodatkach nie można tworzyć ręcznie. W przeciwieństwie do prostych aktywatorów aktywatory instalowane mogą korzystać z usług wymagających autoryzacji.

Reguły instalowane w dodatkach nie wysyłają e-maili z informacją o błędach do użytkownika, gdy napotkają błędy, ponieważ w większości przypadków użytkownik nie może rozwiązać problemu. Z tego powodu należy zaprojektować dodatek tak, aby w miarę możliwości obsługiwał błędy w imieniu użytkownika.

Dodatki mogą używać tych reguł instalowanych:

• Reguły instalowane Open są wykonywane, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub gdy formularz jest otwierany w edytorze (ale nie podczas odpowiadania na formularz).
• Reguły instalowane Edit są wykonywane, gdy użytkownik zmienia wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie jest uruchamiana w odpowiedzi na formatowanie ani inne zmiany, które nie zmieniają wartości komórek.
• Reguły instalowane Change są wykonywane, gdy użytkownik wprowadza dowolną zmianę w arkuszu kalkulacyjnym, w tym edycję formatowania i modyfikacje samego arkusza (np. dodanie wiersza).

• Reguły instalowane Form-submit są wykonywane, gdy zostanie przesłana odpowiedź w Formularzach Google.

  Istnieją 2 wersje reguł przesyłania formularza: jedna dla Arkuszy (gdzie zbierane są odpowiedzi z formularza) i jedna dla Formularzy Google. Obiekt zdarzenia przekazywany do funkcji reguły przesyłania formularza w Arkuszach jest prostszy i zwraca wartości odpowiedzi w prostych tablicach. Obiekt zdarzenia przekazywany do funkcji reguły przesyłania formularza w Formularzach zawiera więcej informacji, które są zawarte w obiekcie FormResponse.

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

Autoryzowanie reguł instalowanych

Zwykle, jeśli deweloper zaktualizuje dodatek, aby używać nowych usług wymagających dodatkowej autoryzacji, użytkownicy zostaną poproszeni o ponowne autoryzowanie dodatku przy następnym użyciu.

Jednak dodatki, które używają reguł, napotykają szczególne problemy z autoryzacją. Wyobraź sobie dodatek, który używa reguły 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 używać nowych usług wymagających dodatkowej autoryzacji, twórca formularza nigdy nie zobaczy okna ponownej autoryzacji, ponieważ nigdy nie otworzył ponownie formularza, a dodatek przestanie działać.

W przeciwieństwie do aktywatorów w zwykłych projektach Apps Script aktywatory w dodatkach są nadal uruchamiane, nawet jeśli 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 , aby ograniczyć dostęp do części kodu, które uległy zmianie między wersjami dodatku.

Przykłady poniżej pokazują zalecaną strukturę, której należy używać w funkcjach reguł, aby uniknąć problemów z autoryzacją. Przykładowa funkcja reguły reaguje na zdarzenie przesyłania formularza w dodatku do Arkuszy Google i, jeśli wymagana jest ponowna autoryzacja, wysyła do użytkownika dodatku e-maila z alertem przy użyciu szablonu 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 instalowane w dodatkach podlegają tym samym ograniczeniom , które obowiązują w przypadku reguł instalowanych w innych rodzajach projektów Apps Script.

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

• Każdy dodatek może mieć tylko 1 regułę każdego typu na użytkownika i dokument. Na przykład w danym arkuszu kalkulacyjnym dany użytkownik może mieć tylko 1 regułę edycji, ale może też mieć regułę przesyłania formularza lub regułę zależną od czasu w tym samym arkuszu. Inny użytkownik z dostępem do tego samego arkusza kalkulacyjnego może mieć własny zestaw reguł.
• Dodatki mogą tworzyć reguły tylko dla pliku, w którym są używane. Oznacza to, że dodatek używany w Dokumencie Google A nie może utworzyć reguły monitorowania otwierania Dokumentu Google B.
• Reguły zależne od czasu nie mogą być uruchamiane częściej niż raz na godzinę.
• Dodatki nie wysyłają automatycznie do użytkownika e-maila, gdy kod uruchamiany przez regułę instalowaną zgłosi wyjątek. Deweloper musi sprawdzić i odpowiednio obsłużyć przypadki niepowodzenia.
• Reguły dodatku przestają być uruchamiane w tych sytuacjach:
  • Jeśli użytkownik odinstaluje dodatek.
  • Jeśli dodatek zostanie wyłączony w dokumencie (po ponownym włączeniu reguła zacznie działać) lub
  • Jeśli deweloper wycofa publikację dodatku lub prześle do sklepu z dodatkami uszkodzoną wersję.
• Funkcje reguł dodatku są wykonywane do momentu, gdy dotrą do kodu, który używa nieautoryzowanej usługi, po czym się zatrzymują. Dotyczy to tylko opublikowanego dodatku. Jeśli jakakolwiek część skryptu wymaga autoryzacji, ta sama reguła w zwykłym projekcie Apps Script lub nieopublikowanym dodatku nie jest w ogóle wykonywana.
• Reguły instalowane podlegają limitom przydziału reguł Apps Script .