Wyzwalacze dodatków do edytora

Wyzwalacze Apps Script powodują wystąpienie określonego skryptu funkcja (funkcja wyzwalacza), która ma być wykonywana za każdym razem, gdy określone zdarzenie ma miejsce. Tylko niektóre zdarzenia mogą powodować uruchamianie reguł. Aplikacja Google Workspace obsługuje inny zestaw zdarzeń.

Po uruchomieniu reguły tworzony jest obiekt zdarzenia. Ta struktura JSON zawiera szczegółowe informacje o wystąpieniu zdarzenia. Informacje zawarte w zdarzeniu czy struktura obiektu jest różna w zależności od typu reguły.

Po utworzeniu obiektu zdarzenia Apps Script przekazuje go jako parametr do . Funkcja aktywatora to funkcja wywołania zwrotnego, wdrożenia i działań, które pozwolą zareagować . Na przykład w wyzwalaczu dodatku edytora służy do tworzenia pozycji menu dodatkowych po otwarciu dokumentu. W tym przypadku zaimplementuj w funkcji aktywatora onOpen(e), aby utworzyć pozycje menu dodatku używając danych z obiektu zdarzenia.

Na tej stronie znajdziesz wytyczne dotyczące używania reguł w edytujący projektów dodatkowych.

Typy aktywatorów dodatków do edytora

Możesz używać większości ogólnych typów aktywatorów dostępnych w projektach Apps Script w dodatkach do Edytora, w tym prostych aktywatorów. i większości reguł, które można zainstalować. dokładny zestaw dostępnych typów aktywatorów zależy od rozszerzenia aplikacji.

W tabeli poniżej znajdziesz typy prostych i możliwych do zainstalowania aktywatorów, które Dodatki do edytora, z których mogą korzystać, i dostarczają linki do odpowiednich obiektów zdarzeń:

Zdarzenie	Obiekt zdarzenia	Proste aktywatory	Aktywatory instalacyjne
Otwórz Otwarto plik edytora.	Dokumenty onOpen obiekt zdarzenia . Obiekty wydarzenia Formularzy onOpen Arkusze onOpen obiekt zdarzenia , Obiekty zdarzeń w Prezentacjach 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 Zawartość komórki arkusza kalkulacyjnego została zmieniona.	Obiekt zdarzenia onEdit	Arkusze function onEdit(e)	Arkusze
Zmiana Zawartość arkusza została zmodyfikowana lub sformatowana.	Obiekt zdarzenia Arkuszy onChange		Arkusze
Przesłanie formularza Formularz Google został przesłany.	Obiekt zdarzenia przesłania formularza w Formularzach . Obiekt zdarzenia przesłania formularza w Arkuszach		Formularze Arkusze.
Ograniczony czasowo (zegar) Reguła uruchamia się w określonym czasie lub w określonym przedziale czasu.	Obiekt zdarzenia zależnego od czasu		Dokumenty Formularze Arkusze pliki Prezentacji

* Otwarte zdarzenie w Formularzach Google nie występuje, gdy użytkownik otworzy , a nie wtedy, gdy edytujący otworzy formularz, aby go zmodyfikować.

Proste aktywatory w dodatkach

Proste aktywatory używają zbioru zarezerwowanego. nie mogą używać usług wymagających autoryzacji oraz automatycznie włączone do użytku. W niektórych przypadkach proste zdarzenie aktywujące może będzie obsługiwana przez wyzwalacz z możliwością zainstalowania.

Aby dodać prosty aktywator do dodatku, zaimplementuj funkcję z jedną z tych zarezerwowanych nazw:

• onOpen(e) działa, gdy użytkownik otwiera dokument, arkusz kalkulacyjny lub prezentacji. Kod onOpen(e) może być także wykonywany po otwarciu formularza w edytorze (ale nie podczas odpowiadania na formularz). Wykonywane jest tylko wtedy, gdy użytkownik uprawnień do edycji danego pliku. Są najczęściej używane do tworzenia pozycje menu.
• Działanie onInstall(e) jest wykonywane, gdy użytkownik zainstaluje dodatek. Zwykle onInstall(e) jest tylko używany do wywoływania funkcji onOpen(e); Dzięki temu menu dodatków będzie widoczne natychmiast po instalacji bez konieczności odświeżania strony przez użytkownika.
• Pole onEdit(e) jest wykonywane, gdy użytkownik zmieni wartość komórki w arkuszu kalkulacyjnym. Ta reguła nie uruchamia się w odpowiedzi na przeniesienie komórki, formatowanie lub inne zmiany, które nie powodują zmiany wartości w komórkach.

Ograniczenia

Proste aktywatory w dodatkach podlegają tym samym ograniczeń dotyczących prostych elementów aktywatory w innych rodzajach projektów Apps Script. Zwróć uwagę na te kwestie ograniczeń przy projektowaniu dodatków:

• Proste aktywatory nie działają, jeśli plik jest otwarty tylko do odczytu (wyświetl lub ). Takie działanie uniemożliwia wypełnianie menu dodatków.
• W pewnych okolicznościach dodatki do Edytora Google Ads uruchamiają tagi onOpen(e) oraz onEdit(e) prostych aktywatorów w trybie bez autoryzacji. Ten tryb przedstawia komplikacje opisane w .
• Proste aktywatory nie mogą używać usług ani podejmować inne działania, które wymagają autoryzacji, z wyjątkiem opisane w model autoryzacji dodatków.
• Proste reguły nie mogą działać dłużej niż 30 sekund. Postaraj się zminimalizować ilość przetwarzania wykonanego przez prostą funkcję wyzwalacza.
• Proste wyzwalacze podlegają aktywatorowi Apps Script limity.

Wyzwalacze do zainstalowania w dodatkach

Dodatki mogą automatyczne tworzenie i modyfikowanie reguł możliwych do zainstalowania. przy użyciu usługi Apps Script Script. dodatek aktywatorów możliwych do zainstalowania nie można tworzyć ręcznie. W przeciwieństwie do prostych reguł Aktywatory możliwe do zainstalowania mogą używać usług, które wymagają autoryzacji.

Aktywatory możliwe do zainstalowania w dodatkach nie wysyłają e-maili o błędach. użytkownikom, którzy napotkają błędy, ponieważ w większości przypadków aby rozwiązać problem. Z tego powodu dodatek powinien być płynnie obsługiwać błędy w imieniu użytkownika, gdy tylko jest to możliwe.

Dodatki mogą używać tych aktywatorów, które można zainstalować:

• Otwarte reguły z możliwością zainstalowania są uruchamiane, gdy użytkownik otworzy dokument. arkusza kalkulacyjnego lub po otwarciu formularza w edytorze (ale nie podczas do formularza).
• Edytuj reguły instalacyjne są wykonywane, gdy użytkownik zmieni wartość komórki w arkusz kalkulacyjny. Ta reguła nie uruchamia się w odpowiedzi na formatowanie lub inne zmiany, które nie zmieniają wartości komórek.
• Zmiana uruchamianych reguł uruchamiających się jest wykonywana, gdy użytkownik wprowadzi arkusza kalkulacyjnego, w tym zmian formatowania i modyfikacji; (np. dodanie wiersza).

• Instalacyjne reguły związane z przesłaniem formularza są uruchamiane, gdy odpowiedź w Formularzu Google jest przesłano.

• Reguły oparte na czasie (nazywane również aktywatorami zegara) uruchamiają się o określonej godzinie lub wielokrotnie na w regularnych odstępach czasu.

Autoryzacja aktywatorów możliwych do zainstalowania

Zwykle, jeśli deweloper zaktualizuje dodatek, aby używał nowych usług, które wymagają w celu przeprowadzenia dodatkowej autoryzacji, użytkownik zostanie poproszony o ponowną autoryzację dodatku za każdym razem, gdy z niej korzystają.

Jednak dodatki korzystające z aktywatorów podlegają specjalnym testom autoryzacyjnym. Wyobraź sobie dodatek, który używa aktywatora do monitorowania przesłanych formularzy: formularza twórca może autoryzować dodatek przy pierwszym użyciu, a potem pozostawić go mogą działać przez miesiące lub lata bez ponownego otwierania formularza. Jeśli programista dodatku zaktualizował dodatek, aby używał nowych usług, które wymaga dodatkowej autoryzacji, twórca nigdy nie zobaczy formularza okna ponownej autoryzacji, ponieważ formularz i dodatek nigdy nie został ponownie otwarty. przestanie działać.

W przeciwieństwie do aktywatorów w zwykłych projektach Apps Script, wyzwalacze w są nadal uruchamiane, nawet jeśli wymagają ponownej autoryzacji. Jednak skrypt nadal kończy się niepowodzeniem, jeśli trafi na wiersz kodu, który wymaga autoryzacji skryptu których nie ma. Aby uniknąć takiej sytuacji, deweloperzy mogą użyć metody ScriptApp.getAuthorizationInfo() do części kodu, które uległy zmianie między opublikowanymi wersjami po zainstalowaniu dodatku.

Poniżej znajduje się przykład zalecanej struktury do użycia w funkcjach aktywujących uniknąć pułapek z autoryzacją. Przykładowa funkcja aktywatora odpowiada na typu „formularz” w dodatku do Arkuszy Google, a w przypadku wysyła do użytkownika dodatku e-mail 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

Aktywatory instalacyjne w dodatkach podlegają tym samym ograniczenia które regulują aktywatory instalacyjne w innych rodzajach projektów Apps Script.

Oprócz tych ograniczeń obowiązują też pewne ograniczenia dotyczące w szczególności:

• Każdy dodatek może mieć tylko 1 wyzwalacz danego typu na użytkownika na dokument. Na przykład w danym arkuszu kalkulacyjnym dany użytkownik może mieć tylko jedną zmianę. chociaż użytkownik może mieć również regułę opartą na przesłaniu formularza w tym samym arkuszu kalkulacyjnym dla reguł opartych na czasie. 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 A Google nie może utworzyć reguły do sprawdzanie, kiedy jest otwarty dokument Google B.
• Reguły oparte na czasie nie mogą być uruchamiane częściej niż raz na godzinę.
• Dodatki nie wysyłają automatycznie e-maila do użytkownika, gdy kod uruchamia się instalacyjny aktywator zgłasza wyjątek. Sprawdzanie zależy od dewelopera i odpowiednio radzić sobie z przypadkami awarii.
• Aktywatory dodatków przestają się uruchamiać w tych sytuacjach:
  • Jeśli użytkownik odinstaluje dodatek:
  • Jeśli dodatek jest wyłączony w dokumencie (po ponownym włączeniu, czynnik uruchamiający ponownie funkcjonuje) lub
  • Jeśli deweloper cofnie publikację dodatku lub prześle jego niedziałającą wersję do w sklepie z dodatkami.
• Dodatkowe funkcje aktywatora są wykonywane, dopóki nie dotrą do kodu, który używa nieautoryzowana usługa, w którym usługa zostanie zatrzymana. Dzieje się tak tylko wtedy, gdy dodatek został opublikowany; ten sam aktywator w zwykłym projekcie Apps Script lub nieopublikowany dodatek w ogóle nie działa, jeśli jakakolwiek część skryptu wymaga autoryzacji.
• Aktywatory możliwe do zainstalowania podlegają aktywatorowi Apps Script limity.