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ą wywoływać reguły, a każda aplikacja Google Workspace obsługuje inny zestaw zdarzeń.

Po uruchomieniu reguły tworzony jest obiekt zdarzenia. Ta struktura JSON zawiera szczegółowe informacje o tym zdarzeniu. Informacje w strukturze obiektów zdarzeń są uporządkowane inaczej 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 odpowiadające na żądanie. Na przykład w dodatku Edytor służy do tworzenia pozycji menu dodatków po otwarciu dokumentu. W tym przypadku wdrożysz funkcję aktywatora onOpen(e), aby utworzyć potrzebne pozycje menu, które mogą być dodatkiem, prawdopodobnie używając danych z obiektu zdarzenia.

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

Rodzaje reguł dodatku do edytora

W dodatkach do edytorów możesz używać większości ogólnych typów aktywatorów dostępnych w projektach Apps Script, w tym prostych reguł i większości instalacyjnych reguł. Dokładny zestaw dostępnych typów aktywatorów zależy od rozszerzenia aplikacji.

Uwaga: w przeciwieństwie do dodatków do edytora dodatki do Google Workspace nie mogą obecnie korzystać z ogólnych ani łatwych do zainstalowania reguł. Zamiast tego używają aktywatorów zaprojektowanych specjalnie dla dodatków do Google Workspace. Więcej informacji znajdziesz w artykule na temat aktywatorów dodatków do Google Workspace.

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

Zdarzenie	Obiekt zdarzenia	Proste aktywatory	Reguły możliwe do zainstalowania
Otwórz Zostanie otwarty plik edytora.	Obiekt zdarzenia onOpen Obiekt zdarzenia onOpen Obiekt zdarzenia 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 Treść komórki arkusza kalkulacyjnego zostanie zmieniona.	Obiekt zdarzenia onEdit	Arkusze function onEdit(e)	Arkusze
Zmień Treść arkusza jest edytowana lub formatowana.	Obiekt zdarzenia onChange w Arkuszach		Arkusze
Przesłanie formularza Przesyłany jest formularz Google.	Zdarzenie: przesłanie formularza z użyciem Formularzy Zdarzenie typu „Przesłanie formularza”		Formularze Arkusze
Na podstawie czasu (zegar) Reguła uruchamia się o określonej godzinie lub w określonym przedziale czasu.	Obiekt zdarzeń ograniczonych czasowo		Dokumenty Formularze Arkusze Prezentacje

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

Proste aktywatory w dodatkach

Proste aktywatory używają zdefiniowanych nazw funkcji, nie mogą korzystać z usług, które wymagają autoryzacji, i są automatycznie włączane do użytku. W niektórych przypadkach proste zdarzenie aktywujące może być obsługiwane przez instalację reguły.

Możesz dodać prosty dodatek do dodatku, implementując funkcję z jedną z tych zarezerwowanych nazw:

• onOpen(e) jest uruchamiany, gdy użytkownik otworzy dokument, arkusz kalkulacyjny lub prezentację. onOpen(e) może też wykonać się po otwarciu formularza w edytorze (ale nie podczas odpowiadania na formularz). Wykonywana jest tylko wtedy, gdy użytkownik ma uprawnienia do edycji danego pliku, i najczęściej jest używana do tworzenia pozycji menu.
• onInstall(e) jest wykonywany, gdy użytkownik zainstaluje dodatek. Zazwyczaj funkcja onInstall(e) jest używana do wywołania metody onOpen(e). Dzięki temu menu dodatków pojawia się od razu po zainstalowaniu, bez potrzeby odświeżania strony przez użytkownika.
• onEdit(e) działa, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ten aktywator nie jest uruchamiany 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:

• Proste reguły nie są uruchamiane, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie). To działanie zapobiega wypeł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 pewnymi komplikacjami, zgodnie z modelem autoryzacji dodatków.
• Proste aktywatory nie mogą używać usług ani wykonywać innych działań, które wymagają autoryzacji, z wyjątkiem sytuacji opisanych w modelu autoryzacji dodatkowego.
• Proste reguły mogą trwać maksymalnie 30 sekund. Staraj się minimalizować ilość przetwarzania wykonywanego za pomocą prostej funkcji aktywatora.
• Proste aktywatory podlegają limitom limitów aktywatorów Apps Script.

Reguły do zainstalowania w dodatkach

Dodatki mogą automatycznie tworzyć i modyfikować aktywatory instalowane za pomocą usługi Apps Script Script. Aktywatorów uruchamiających dodatki nie można tworzyć ręcznie. Inaczej niż w przypadku prostych aktywatorów, które można zainstalować, można używać usług wymagających autoryzacji.

Reguły możliwe do zainstalowania w dodatkach nie wysyłają do użytkownika e-maili z błędami, ponieważ w większości przypadków użytkownik nie jest w stanie rozwiązać problemu. Dlatego zaprojektuj dodatek tak, aby w miarę możliwości obsługiwał błędy w imieniu użytkownika.

Dodatki mogą używać następujących aktywatorów:

• Wyzwalacze otwarte są uruchamiane, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub formularz w edytorze (ale nie podczas odpowiadania na formularz).
• Edytuj reguły możliwe do zainstalowania, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie uruchamia się w odpowiedzi na formatowanie ani inne zmiany, które nie zmieniają wartości komórek.
• Wyzwalacze montowania, które można zainstalować, są wykonywane, gdy użytkownik wprowadza jakiekolwiek zmiany w arkuszu kalkulacyjnym, między innymi formatowanie i modyfikacje samego arkusza kalkulacyjnego (np. przez dodanie wiersza).

• Reguły, które można zainstalować za pomocą przesyłania formularza, są wykonywane po przesłaniu odpowiedzi z formularza Google.

  Uwaga: dostępne są 2 wersje reguł przesyłania formularzy: jedna dla Arkuszy (w której zbierane są odpowiedzi na pytania formularza) i jedna dla Formularzy Google. Obiekt zdarzenia przekazany do funkcji aktywatora przesłania arkusza jest prostszy i zwraca wartości odpowiedzi w prostych tablicach. Obiekt zdarzenia przekazany do funkcji aktywacji przesłania formularza zawiera więcej informacji zawartych w obiekcie FormResponse.

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

Autoryzowanie aktywatorów możliwych do zainstalowania

Normalnie jeśli deweloper zaktualizuje dodatek, aby korzystał z nowych usług, które wymagają dodatkowej autoryzacji, użytkownicy zobaczą prośbę o ponowne uwierzytelnienie dodatku przy kolejnym użyciu.

W przypadku dodatków, które korzystają z aktywatorów, obowiązują specjalne wymagania dotyczące autoryzacji. Wyobraź sobie dodatek, który korzysta z reguły do monitorowania przesyłania formularzy: twórca formularza może autoryzować dodatek po pierwszym użyciu, a następnie pozostawić go na kilka miesięcy lub lat, nie otwierając ponownie formularza. Gdy twórca dodatku zaktualizuje dodatek i zacznie używać nowych usług, które wymagają dodatkowej autoryzacji, twórca formularza nie zobaczy okna z prośbą o ponowną autoryzację, bo nigdy nie otworzy go ponownie, a dodatek przestanie działać.

W odróżnieniu od aktywatorów w zwykłych projektach Apps Script, aktywatory w dodatkach będą nadal uruchamiane, nawet jeśli będą wymagały ponownej autoryzacji. Skrypt nadal jednak nie powiedzie się, jeśli osiągnie wiersz kodu, który wymaga autoryzacji. Aby uniknąć tej sytuacji, deweloperzy mogą użyć metody ScriptApp.getAuthorizationInfo(), aby odblokować dostęp do części 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 aktywatora, aby uniknąć problemów z autoryzacją. Przykładowa funkcja uruchamiająca odpowiada na przesłanie formularza za pomocą dodatku do Arkuszy Google i, jeśli wymagane jest ponowne uwierzytelnienie, wysyła do użytkownika e-maila z alertem przy użyciu szablonu HTML.

Kod.gs

reguły/formularz/kod.gs

Wyświetl w GitHubie

/**
 * 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.
  }
}

autoryzacja_e-mail.html

wyzwalacze/formularz/e-mail_autoryzacji.html

Wyświetl w GitHubie

<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, które można zainstalować w dodatkach, podlegają takim samym ograniczeniom, które regulują uruchamianie reguł w innych typach projektów Apps Script.

Oprócz tych ograniczeń w instalacjach uwzględniających dodatek mają zastosowanie te ograniczenia:

• Każdy dodatek może mieć tylko jedną regułę każdego typu na użytkownika na dokument. Na przykład w danym arkuszu kalkulacyjnym dany użytkownik może mieć tylko jedną regułę edycji, ale w jednym arkuszu może też mieć aktywator przesłania formularza lub regułę opartą na czasie. Inny użytkownik mający dostęp do tego samego arkusza kalkulacyjnego może mieć własny zestaw aktywatorów.
• Dodatki mogą tworzyć aktywatory tylko dla pliku, w którym jest 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 oparte na czasie 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 generuje wyjątek. To do dewelopera należy kontrola i sprawne rozwiązywanie problemów.
• Reguły dodatku przestaną się uruchamiać w tych sytuacjach:
  • Jeśli użytkownik odinstaluje dodatek,
  • Jeśli dodatek jest wyłączony w dokumencie (jeśli zostanie ponownie włączony, reguła znowu stanie się aktywna) lub
  • Deweloper cofnie publikację dodatku lub prześle jego uszkodzoną wersję do sklepu z dodatkami.
• Funkcje aktywatora dodatkowego są wykonywane, dopóki nie osiągną kodu, który powoduje użycie nieuwierzytelnionej usługi. W tym momencie są one przerywane. Dzieje się tak tylko wtedy, gdy dodatek zostanie opublikowany. Ten sam aktywator w normalnym projekcie Apps Script lub nieopublikowany dodatek jest w ogóle niewykonany, jeśli jakakolwiek część skryptu wymaga autoryzacji.
• Reguły, które można zainstalować, podlegają limitom limitów aktywatorów Apps Script.