Wyzwalacze proste

Aktywatory pozwalają Apps Script uruchamiać funkcję automatycznie, gdy wystąpi określone zdarzenie, takie jak otwarcie dokumentu. Proste aktywatory to zestaw zarezerwowanych funkcji wbudowanych w Apps Script, takich jak funkcja onOpen(e), które są wykonywane, gdy użytkownik otworzy plik Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Reguły do zainstalowania mają więcej możliwości niż aktywatory proste, ale muszą zostać aktywowane przed użyciem. W przypadku obu typów aktywatorów Apps Script przekazuje wywołaną funkcję obiekt zdarzenia z informacjami o kontekście, w którym wystąpiło zdarzenie.

Wprowadzenie

Aby użyć prostego aktywatora, po prostu utwórz funkcję korzystającą z jednej z tych zarezerwowanych nazw funkcji:

  • onOpen(e) jest uruchamiany, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, które ma uprawnienia do edycji.
  • onInstall(e) jest uruchamiany, gdy użytkownik zainstaluje dodatek do edytora z poziomu Dokumentów, Arkuszy, Prezentacji lub Formularzy Google.
  • onEdit(e) jest uruchamiany, gdy użytkownik zmieni wartość w arkuszu kalkulacyjnym.
  • onSelectionChange(e) jest uruchamiany, gdy użytkownik zmieni zaznaczenie w arkuszu kalkulacyjnym.
  • doGet(e) działa, gdy użytkownik otwiera aplikację internetową lub program wysyła do aplikacji internetowej żądanie HTTP GET.
  • doPost(e) działa, gdy program wysyła do aplikacji internetowej żądanie HTTP POST.

Parametr e w nazwach funkcji powyżej to obiekt zdarzenia przekazywany do funkcji. Obiekt zawiera informacje o kontekście, który spowodował uruchomienie reguły, ale korzystanie z niego jest opcjonalne.

Ograniczenia

Proste reguły uruchamiają się automatycznie, nie prosząc 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świetlania lub komentowania).
  • Wykonanie skryptów i żądania do interfejsu API nie powodują uruchomienia aktywatorów. Na przykład wywołanie funkcji Range.setValue() w celu edytowania komórki nie powoduje uruchomienia reguły onEdit arkusza kalkulacyjnego.
  • Nie będzie miał dostępu do usług, które wymagają autoryzacji. Na przykład prosty aktywator nie może wysłać e-maila, ponieważ usługa Gmail wymaga autoryzacji, a prosty aktywator może przetłumaczyć wyrażenie przy użyciu anonimowej usługi językowej.
  • Mogą modyfikować powiązany plik, ale nie mają dostępu do innych plików, ponieważ wymaga to autoryzacji.
  • Określenie tożsamości bieżącego użytkownika może być niemożliwe w zależności od złożonego zestawu ograniczeń bezpieczeństwa.
  • Nie mogą trwać dłużej niż 30 sekund.
  • W pewnych okolicznościach dodatki do edycji uruchamiają proste aktywatory onOpen(e) i onEdit(e) w trybie braku autoryzacji, co może się wiązać z dodatkowymi komplikacjami. Więcej informacji znajdziesz w przewodniku po cyklu życia autoryzacji dodatków.
  • Proste aktywatory podlegają limitom aktywatora Apps Script.

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

onOpen(e)

Aktywator onOpen(e) uruchamia się automatycznie, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, który ma uprawnienia do edycji. Reguła nie działa, gdy odpowiadasz na formularz, tylko gdy go otwierasz, aby go edytować. onOpen(e) służy najczęściej do dodawania niestandardowych elementów menu w Arkuszach, Prezentacjach, Dokumentach i 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)

Aktywator onInstall(e) uruchamia się automatycznie, gdy użytkownik zainstaluje dodatek do edytora z poziomu Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Aktywator nie będzie działać, gdy użytkownik zainstaluje dodatek ze strony Google Workspace Marketplace. Pamiętaj, że obowiązują pewne ograniczenia dotyczące czynności, które może wykonać onInstall(e). Dowiedz się więcej o autoryzacji. Najpopularniejszym zastosowaniem onInstall(e) jest po prostu wywoływanie funkcji onOpen(e) w celu dodania niestandardowych menu. W końcu po zainstalowaniu dodatku plik jest już otwarty, więc onOpen(e) nie działa samoczynnie, dopóki plik nie 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)

Aktywator onEdit(e) uruchamia się automatycznie, gdy użytkownik zmieni wartość dowolnej komórki w arkuszu kalkulacyjnym. Większość aktywatorów onEdit(e) prawidłowo odpowiada na podstawie informacji z obiektu zdarzenia. Na przykład funkcja onEdit(e) poniżej ustawia komentarz do komórki, w której jest zapisana data ostatniej 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)

Aktywator onSelectionChange(e) uruchamia się automatycznie, gdy użytkownik zmieni wybór w arkuszu kalkulacyjnym. Aby aktywować regułę, trzeba odświeżyć arkusz po jego dodaniu i otwarciu.

Jeśli zaznaczenie zostanie przeniesione między wieloma komórkami w krótkim czasie, niektóre zdarzenia zmiany wyboru mogą zostać pominięte w celu skrócenia czasu oczekiwania. Jeśli np. w ciągu 2 sekund od siebie nastąpiła duża liczba zmian wyboru, aktywator onSelectionChange(e) aktywuje tylko pierwsza i ostatnia zmiana.

W przykładzie poniżej, jeśli wybrana jest pusta komórka, funkcja onSelectionChange(e) ustawia tło komórki na czerwone.

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)doPost(e)

Aktywator doGet(e) uruchamia się automatycznie, gdy użytkownik otwiera aplikację internetową lub program wysyła do aplikacji internetowej żądanie HTTP GET. doPost(e) działa, gdy program wysyła do aplikacji internetowej żądanie HTTP POST. Dokładniejsze informacje 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ą opisanym wyżej ograniczeniom.

Dostępne typy reguł

Jeśli ograniczenia prostych aktywatorów sprawiają, że nie spełniają one Twoich potrzeb, zamiast tego możesz użyć reguły z możliwością zainstalowania. W tabeli poniżej podsumowujemy, jakie typy reguł są dostępne w przypadku poszczególnych typów zdarzeń. Na przykład Arkusze, Prezentacje, Formularze i Dokumenty Google obsługują proste reguły otwierania, ale tylko Arkusze, Dokumenty i Formularze Google obsługują te reguły.

Zdarzenie Proste aktywatory Aktywatory 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
Na podstawie czasu (zegar)
Arkusze
Prezentacje
Formularze
Dokumenty
Samodzielne
Pobierz
Samodzielne

function doGet(e)

Post
Samodzielne

function doPost(e)

* Zdarzenie otwarcia Formularzy Google nie zachodzi, gdy użytkownik otworzy formularz w celu udzielenia odpowiedzi, ale gdy to zrobi edytujący, aby go zmodyfikować.