Wyzwalacze proste

Reguły umożliwiają automatyczne uruchamianie funkcji Apps Script po wystąpieniu określonego zdarzenia, takiego jak otwarcie dokumentu. Proste wyzwalacze to zestaw zarezerwowanych funkcji wbudowanych w Apps Script, takich jak funkcja onOpen(e), która jest wykonywana, gdy użytkownik otwiera plik Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Aktywatory instalowane mają więcej możliwości niż proste aktywatory, ale przed użyciem trzeba je aktywować. W przypadku obu rodzajów wyzwalaczy Apps Script przekazuje wywołanej funkcji obiekt zdarzenia, który zawiera informacje o kontekście, w którym wystąpiło zdarzenie.

Pierwsze kroki

Aby użyć prostego wyzwalacza, wystarczy utworzyć funkcję, która używa jednej z tych zarezerwowanych nazw funkcji:

  • onOpen(e) jest uruchamiana, gdy użytkownik otwiera arkusz kalkulacyjny, dokument, prezentację lub formularz, który może edytować.
  • onInstall(e) jest uruchamiana, gdy użytkownik instaluje dodatek do edytora w Dokumentach, Arkuszach, Prezentacjach lub Formularzach Google.
  • onEdit(e) uruchamia się, gdy użytkownik zmieni wartość w arkuszu kalkulacyjnym.
  • onSelectionChange(e) jest uruchamiana, gdy użytkownik zmienia zaznaczenie w arkuszu kalkulacyjnym.
  • doGet(e) jest uruchamiana, gdy użytkownik odwiedza aplikację internetową lub program wysyła do niej żądanie HTTP GET.
  • doPost(e) jest uruchamiana, gdy program wysyła żądanie HTTP POST do aplikacji internetowej.

Parametr e w nazwach funkcji powyżej to obiekt zdarzenia, który jest przekazywany do funkcji. Obiekt zawiera informacje o kontekście, w którym nastąpiło wywołanie, ale jego użycie jest opcjonalne.

Ograniczenia

Proste wyzwalacze uruchamiają się automatycznie, bez proszenia użytkownika o autoryzację, dlatego podlegają kilku ograniczeniom:

  • Skrypt musi być powiązany z plikiem Arkuszy, Prezentacji, Dokumentów lub Formularzy Google albo być dodatkiem rozszerzającym jedną z tych aplikacji.
  • Nie działają one, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie).
  • Wykonania skryptów i żądania do interfejsu API nie powodują uruchamiania aktywatorów. Na przykład wywołanie funkcji Range.setValue() w celu edytowania komórki nie spowoduje uruchomienia wyzwalacza onEdit arkusza kalkulacyjnego.
  • Nie mogą oni korzystać z usług, które wymagają autoryzacji. Na przykład prosty wyzwalacz nie może wysłać e-maila, ponieważ usługa Gmail wymaga autoryzacji, ale może przetłumaczyć frazę za pomocą usługi językowej, która jest anonimowa.
  • Mogą modyfikować plik, z którym są powiązani, ale nie mają dostępu do innych plików, ponieważ wymaga to autoryzacji.
  • W zależności od złożonego zestawu ograniczeń bezpieczeństwa mogą one być w stanie określić tożsamość bieżącego użytkownika lub nie.
  • Nie mogą trwać dłużej niż 30 sekund.
  • W pewnych okolicznościach dodatki do edytora uruchamiają onOpen(e)i onEdit(e) proste wyzwalacze w trybie bez autoryzacji, co powoduje pewne dodatkowe komplikacje. Więcej informacji znajdziesz w przewodniku po cyklu autoryzacji dodatku.
  • Proste aktywatory podlegają limitom aktywatorów Apps Script.

Te ograniczenia nie dotyczą aplikacji doGet(e) ani doPost(e).

onOpen(e)

Wywoływacz onOpen(e) uruchamia się automatycznie, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, które może edytować. (Wywoływacz nie uruchamia się podczas odpowiadania na formularz, tylko podczas otwierania formularza w celu jego edycji). onOpen(e) jest najczęściej używany do dodawania niestandardowych pozycji menu w Arkuszach, Prezentacjach, Dokumentach lub Formularzach Google.

triggers/triggers.gs
/**
 * The event handler triggered when opening the spreadsheet.
 * @param {Event} e The onOpen event.
 * @see https://developers.google.com/apps-script/guides/triggers#onopene
 */
function onOpen(e) {
  // Add a custom menu to the spreadsheet.
  SpreadsheetApp.getUi() // Or DocumentApp, SlidesApp, or FormApp.
      .createMenu('Custom Menu')
      .addItem('First item', 'menuItem1')
      .addToUi();
}

onInstall(e)

Wywoływacz onInstall(e) uruchamia się automatycznie, gdy użytkownik zainstaluje dodatek do edytora w Dokumentach, Arkuszach, Prezentacjach lub Formularzach Google. Reguła nie zostanie uruchomiona, gdy użytkownik zainstaluje dodatek ze strony Google Workspace Marketplace. Pamiętaj, że istnieją pewne ograniczenia dotyczące tego, co może robić onInstall(e). Więcej informacji o autoryzacji Najczęstsze zastosowanie onInstall(e) to po prostu wywołanie onOpen(e) w celu dodania menu niestandardowych. W końcu po zainstalowaniu dodatku plik jest już otwarty, więc funkcja onOpen(e) nie działa samodzielnie, chyba że plik zostanie ponownie otwarty.

triggers/triggers.gs
/**
 * The event handler triggered when installing the add-on.
 * @param {Event} e The onInstall event.
 * @see https://developers.google.com/apps-script/guides/triggers#oninstalle
 */
function onInstall(e) {
  onOpen(e);
}

onEdit(e)

Wywoływacz onEdit(e) uruchamia się automatycznie, gdy użytkownik zmieni wartość dowolnej komórki w arkuszu kalkulacyjnym. Większość onEdit(e) wyzwalaczy używa informacji z obiektu zdarzenia, aby odpowiednio reagować. Na przykład funkcja onEdit(e) poniżej ustawia komentarz w komórce, która rejestruje ostatnią datę edycji.

triggers/triggers.gs
/**
 * The event handler triggered when editing the spreadsheet.
 * @param {Event} e The onEdit event.
 * @see https://developers.google.com/apps-script/guides/triggers#onedite
 */
function onEdit(e) {
  // Set a comment on the edited cell to indicate when it was changed.
  const range = e.range;
  range.setNote('Last modified: ' + new Date());
}

onSelectionChange(e)

Wywoływacz onSelectionChange(e) uruchamia się automatycznie, gdy użytkownik zmieni wybór w arkuszu kalkulacyjnym. Aby aktywować ten wyzwalacz, musisz odświeżyć arkusz kalkulacyjny po dodaniu wyzwalacza i za każdym razem, gdy go otwierasz.

Jeśli zaznaczenie szybko przesuwa się między wieloma komórkami, niektóre zdarzenia zmiany zaznaczenia mogą zostać pominięte, aby zmniejszyć opóźnienie. Jeśli na przykład w ciągu 2 sekund nastąpi wiele zmian wyboru, tylko pierwsza i ostatnia z nich aktywują regułę onSelectionChange(e).

W przykładzie poniżej, jeśli wybierzesz pustą komórkę, funkcja onSelectionChange(e) ustawi czerwone tło komórki.

triggers/triggers.gs
/**
 * The event handler triggered when the selection changes in the spreadsheet.
 * @param {Event} e The onSelectionChange event.
 * @see https://developers.google.com/apps-script/guides/triggers#onselectionchangee
 */
function onSelectionChange(e) {
  // Set background to red if a single empty cell is selected.
  const range = e.range;
  if (range.getNumRows() === 1 &&
    range.getNumColumns() === 1 &&
    range.getCell(1, 1).getValue() === '') {
    range.setBackground('red');
  }
}

doGet(e) i doPost(e)

Wywoływacz doGet(e) uruchamia się automatycznie, gdy użytkownik odwiedza aplikację internetową lub gdy program wysyła żądanie HTTP GET do aplikacji internetowej. Wywoływacz doPost(e) uruchamia się, gdy program wysyła żądanie HTTP POST do aplikacji internetowej. Więcej informacji o tych wywoływaczach znajdziesz w przewodnikach dotyczących aplikacji internetowych, usługi HTML i usługi Content. Pamiętaj, że doGet(e) i doPost(e) nie podlegają ograniczeniom wymienionym powyżej.

Dostępne typy reguł

Jeśli ograniczenia dotyczące prostych wyzwalaczy uniemożliwiają spełnienie Twoich potrzeb, możesz zamiast nich użyć wyzwalacza instalowanego. W tabeli poniżej znajdziesz podsumowanie typów wyzwalaczy dostępnych w przypadku poszczególnych typów zdarzeń. Na przykład Arkusze, Prezentacje, Formularze i Dokumenty Google obsługują proste wyzwalacze otwierania, ale tylko Arkusze, Dokumenty i Formularze obsługują wyzwalacze otwierania, które można zainstalować.

Zdarzenie Proste aktywatory Aktywatory możliwe do zainstalowania
Otwórz
Arkusze
Prezentacje
Formularze*
Dokumenty

function onOpen(e)
Arkusze
Formularze*
Dokumenty
Edytuj
Arkusze

function onEdit(e)
Arkusze
Zmiana wyboru
Arkusze

function onSelectionChange(e)
Zainstaluj
Arkusze
Prezentacje
Formularze
Dokumenty

function onInstall(e)
Zmień
Arkusze
Przesłanie formularza
Arkusze
Formularze
Zależne od czasu (zegar)
Arkusze
Prezentacje
Formularze
Dokumenty
Samodzielne
Pobierz
Samodzielne

function doGet(e)
Opublikuj
Samodzielne

function doPost(e)

* 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ć.