Wyzwalacze proste

Reguły umożliwiają automatyczne uruchamianie funkcji Google Apps Script po wystąpieniu określonego zdarzenia, np. otwarciu 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 oferują więcej możliwości niż aktywatory proste, ale przed użyciem trzeba je aktywować. W przypadku obu rodzajów aktywatorów Apps Script przekazuje do aktywowanej funkcji obiekt zdarzenia, który zawiera informacje o kontekście, w którym wystąpiło zdarzenie.

Informacje o tym, jak używać wyzwalaczy w projektach dodatków do Google Workspace, znajdziesz w artykule Wyzwalacze w dodatkach do Google Workspace.

Pierwsze kroki

Aby użyć prostego aktywatora, utwórz 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 wybór w arkuszu kalkulacyjnym.
• doGet(e) jest uruchamiana, gdy użytkownik odwiedza aplikację internetową lub program wysyła żądanie HTTP GET do aplikacji internetowej.
• 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, który spowodował uruchomienie wyzwalacza, ale korzystanie z niego 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ą, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie).
• Wykonania skryptów i żądania 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 Language, 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 życia autoryzacji dodatku.
• Proste aktywatory podlegają limitom aktywatorów Apps Script.

Te ograniczenia nie dotyczą 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 Google, Prezentacjach, Dokumentach i Formularzach Google.

/**
 * 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)

onInstall(e) Wywoływacz uruchamia się automatycznie, gdy użytkownik zainstaluje dodatek do edytora w Dokumentach, Arkuszach, Prezentacjach lub Formularzach Google. Reguła nie jest uruchamiana, gdy użytkownik instaluje dodatek ze strony Google Workspace Marketplace. Najczęstszym zastosowaniem onInstall(e) jest wywoływanie onOpen(e) w celu dodania menu niestandardowych. Po zainstalowaniu dodatku plik jest już otwarty, więc funkcja onOpen(e) nie uruchamia się sama, chyba że plik zostanie ponownie otwarty. Pamiętaj, że istnieją pewne ograniczenia dotyczące tego, co może robić onInstall(e). Więcej informacji o autoryzacji

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

/**
 * 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()}`);
}

Reguła onEdit() kolejkuje maksymalnie 2 zdarzenia powodujące uruchomienie reguły.

onSelectionChange(e)

Wywoływacz onSelectionChange(e) uruchamia się automatycznie, gdy użytkownik zmieni wybór w arkuszu kalkulacyjnym. Aby aktywować ten wyzwalacz, odśwież 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 tym przykładzie, jeśli zaznaczysz pustą komórkę, funkcjaonSelectionChange(e) ustawi czerwone tło komórki.

/**
 * 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 treści. Pamiętaj, że doGet(e) i doPost(e) nie podlegają wymienionym powyżej ograniczeniom.

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 Google, Prezentacje, Formularze i Dokumenty obsługują proste wyzwalacze otwierania, ale tylko Arkusze, Dokumenty i Formularze obsługują wyzwalacze otwierania, które można zainstalować.

Zdarzenie	Proste reguły	Aktywatory możliwe do zainstalowania
Otwórz	function onOpen(e)
Edytuj	function onEdit(e)
Zmiana wyboru	function onSelectionChange(e)
Zainstaluj	function onInstall(e)
Zmień
Przesłanie formularza
Zależne od czasu (zegar)
Pobierz	function doGet(e)
Opublikuj	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ć.