Wyzwalacze proste

Aktywatory umożliwiają skryptowi Apps Script automatyczne uruchamianie funkcji po wystąpieniu określonego zdarzenia, np. otwarcia dokumentu. Proste aktywatory 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. Reguły instalacyjne oferują więcej możliwości niż proste reguły, ale muszą zostać aktywowane przed użyciem. W przypadku obu typów aktywatorów Apps Script przekazuje uruchamianą funkcję obiekt zdarzenia zawierający informacje o kontekście, w którym wystąpiło zdarzenie.

Pierwsze kroki

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

  • onOpen(e) uruchamia się, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, który użytkownik może edytować.
  • onInstall(e) działa, gdy użytkownik zainstaluje dodatek do edytora z poziomu Dokumentów, Arkuszy, Prezentacji lub Formularzy Google.
  • onEdit(e) działa, gdy użytkownik zmienia wartość w arkuszu kalkulacyjnym.
  • onSelectionChange(e) działa, gdy użytkownik zmieni wybór w arkuszu kalkulacyjnym.
  • doGet(e) działa, gdy użytkownik odwiedza aplikację internetową lub program wysyła do aplikacji internetowej żądanie HTTP GET.
  • doPost(e) działa, gdy program wysyła żądanie HTTP POST do aplikacji internetowej.

Parametr e w powyższych nazwach funkcji jest obiektem zdarzenia przekazywanym do funkcji. Obiekt zawiera informacje o kontekście, który spowodował uruchomienie reguły, ale użycie go jest opcjonalne.

Ograniczenia

Proste reguły są uruchamiane automatycznie, bez pytania użytkownika o zgodę, dlatego podlegają kilku ograniczeniom:

  • Skrypt musi być powiązany z plikiem Arkuszy, Prezentacji, Dokumentów lub Formularzy Google bądź być dodatkiem, który rozszerza jedną z tych aplikacji.
  • Nie działają, jeśli plik jest otwarty w trybie tylko do odczytu (wyświetlanie lub komentowanie).
  • Wykonanie skryptu i żądanie interfejsu API nie powoduje uruchomienia aktywatorów. Na przykład wywołanie metody Range.setValue() w celu edytowania komórki nie powoduje uruchomienia reguły onEdit arkusza kalkulacyjnego.
  • Nie mają 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 z użyciem usługi języka, która jest anonimowa.
  • Mogą modyfikować plik, z którym są powiązane, ale nie mają dostępu do innych plików, bo wymaga to autoryzacji.
  • Określenie tożsamości obecnego użytkownika może być niemożliwe w zależności od złożonego zestawu ograniczeń zabezpieczeń.
  • 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 bez autoryzacji, co stwarza dodatkowe komplikacje. Więcej informacji znajdziesz w przewodniku po cyklu autoryzacji dodatku.
  • Proste aktywatory podlegają limitom reguł Apps Script.

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

onOpen(e)

Wyzwalacz onOpen(e) uruchamia się automatycznie, gdy użytkownik otwiera arkusz kalkulacyjny, dokument, prezentację lub formularz, do którego edycji ma uprawnienia do edycji. (reguła nie działa podczas odpowiadania na formularz, tylko po otwarciu formularza w celu jego edycji). onOpen(e) jest najczęściej używany do dodawania niestandardowych pozycji menu do Arkuszy, Prezentacji, Dokumentów lub Formularzy 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)

Reguła 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 istnieją pewne ograniczenia dotyczące działania usługi onInstall(e). Dowiedz się więcej o autoryzacji. Najczęstszym zastosowaniem funkcji onInstall(e) jest wywoływanie funkcji onOpen(e) w celu dodania menu niestandardowych. Po zainstalowaniu dodatku plik jest już otwarty, więc onOpen(e) nie uruchomi się 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)

Reguła onEdit(e) uruchamia się automatycznie, gdy użytkownik zmieni wartość dowolnej komórki w arkuszu kalkulacyjnym. Większość aktywatorów onEdit(e) używa informacji w obiekcie zdarzenia, aby odpowiednio odpowiedzieć. Na przykład funkcja onEdit(e) poniżej ustawia komentarz w komórce, która rejestruje czas 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)

Reguła onSelectionChange(e) uruchamia się automatycznie, gdy użytkownik zmieni wybór w arkuszu kalkulacyjnym. Aby aktywować tę regułę, musisz odświeżać arkusz kalkulacyjny po dodaniu reguły i każdym otwarciu arkusza kalkulacyjnego.

Jeśli zaznaczenie zostanie przeniesione między wieloma komórkami w krótkim czasie, niektóre zdarzenia zmiany zaznaczenia mogą zostać pominięte, aby zmniejszyć czas oczekiwania. Jeśli na przykład w ciągu 2 sekund od siebie następuje wiele zmian wyboru, regułę onSelectionChange(e) aktywuje tylko pierwsza i ostatnia zmiana wyboru.

Jeśli w przykładzie poniżej wybierzesz pustą komórkę, funkcja onSelectionChange(e) ustawi jej tło 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) i doPost(e)

Aktywator doGet(e) uruchamia się automatycznie, gdy użytkownik odwiedza aplikację internetową lub program wysyła do aplikacji internetowej żądanie HTTP GET. doPost(e) uruchamia się, gdy program wysyła żądanie HTTP POST do aplikacji internetowej. Te aktywatory szczegółowo opisujemy w przewodnikach po aplikacjach internetowych, usłudze HTML i usłudze treści. Pamiętaj, że wymienione powyżej ograniczenia nie dotyczą doGet(e) ani doPost(e).

Dostępne typy reguł

Jeśli ograniczenia prostego aktywatora nie spełniają Twoich oczekiwań, zamiast tego może zadziałać wyzwalacz z możliwością zainstalowania. Poniższa tabela zawiera podsumowanie typów aktywatorów dostępnych w przypadku poszczególnych typów zdarzeń. Na przykład Arkusze, Prezentacje, Formularze i Dokumenty Google obsługują proste reguły otwarte, ale tylko Arkusze, Dokumenty i Formularze obsługują zainstalowane reguły otwarte.

Zdarzenie Proste wyzwalacze Wyzwalacze 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)
Opublikuj posta
Samodzielne

function doPost(e)

* Zdarzenie otwarte w Formularzach Google nie występuje, gdy użytkownik otworzy formularz, żeby odpowiedzieć, ale gdy edytujący otworzy formularz, aby go zmodyfikować.