Wyzwalacze proste

Aktywatory umożliwiają skryptowi Apps Script automatyczne uruchamianie funkcji po wystąpieniu określonego zdarzenia. takich jak otwarcie dokumentu. Proste wyzwalacze są ustawione zarezerwowanych funkcji wbudowanych w Apps Script, takich jak onOpen(e), który jest uruchamiany, gdy użytkownik otwiera plik Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Wyzwalacze instalacyjne oferują więcej niż proste aktywatory, ale trzeba je aktywować przed użyciem. Zarówno dla typy wyzwalaczy, Apps Script przekazuje wyzwoloną funkcję obiekt zdarzenia zawierający informacje o kontekście zdarzenia.

Pierwsze kroki

Aby użyć prostego aktywatora, wystarczy utworzyć funkcję korzystającą z jednego z tych zarezerwowane nazwy funkcji:

  • onOpen(e) uruchamia się, gdy użytkownik otwiera arkusz kalkulacyjny, dokument, prezentację lub który użytkownik może edytować.
  • onInstall(e) działa, gdy użytkownik zainstaluje Dodatek do edytora dostępny w aplikacji Dokumenty, Arkusze, Prezentacje lub Formularze 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 korzysta z aplikacji internetowej. albo 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 nazwach funkcji powyżej jest parametrem obiekt zdarzenia przekazywany do . Obiekt zawiera informacje o kontekście, który spowodował do uruchomienia reguły, ale korzystanie z niej jest opcjonalne.

Ograniczenia

Ponieważ proste reguły uruchamiają się automatycznie, bez pytania użytkownika o to podlegają kilku ograniczeniom:

  • Skrypt musi być powiązany z tagiem Google Arkuszy, Prezentacji, Dokumentów lub Formularzy albo dodatek, który stanowi rozszerzenie jednego 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. Przykład: dzwonię pod numer Range.setValue() nie powoduje uruchomienia reguły onEdit arkusza kalkulacyjnego.
  • Nie mają dostępu do usług, które wymagają autoryzacji. Przykład: prosty wyzwalacz nie może wysłać e-maila, ponieważ Usługa Gmail wymaga autoryzacji, ale prosty wyzwalacz może przetłumaczyć wyrażenie z Usługa językowa, która jest anonimowa.
  • Mogą modyfikować plik, z którym są powiązane, ale nie mają dostępu do innych plików ponieważ wymagałoby to autoryzacji.
  • Mogą oni nie być w stanie określić tożsamości obecnego użytkownika, w zależności od złożonym zestawem ograniczeń związanych z zabezpieczeniami.
  • Nie mogą trwać dłużej niż 30 sekund.
  • W pewnych okolicznościach Dodatki do edytora uruchamiają onOpen(e) i proste aktywatory (onEdit(e)) w trybie bez autoryzacji, które prezentują kilka dodatkowych komplikacji. Więcej informacji: cyklu autoryzacji dodatku.
  • Proste aktywatory podlegają aktywatorowi Apps Script limity.

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

onOpen(e)

Reguła onOpen(e) uruchamia się automatycznie, gdy użytkownik otwiera arkusz kalkulacyjny. dokument, prezentację lub formularz, które mogą edytować. (Parametr nie działa, gdy odpowiadasz na formularz, tylko po otwarciu formularza ją edytować). onOpen(e) jest najczęściej używany do dodawania niestandardowych elementów menu do Arkuszy, Prezentacji, Dokumentów lub Formularze.

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 dostępny w aplikacji Dokumenty, Arkusze, Prezentacje lub Formularze Google. Reguła nie będzie działać, jeśli użytkownik instaluje dodatek ze Google Workspace Marketplace, witryny. Pamiętaj, że istnieją pewne ograniczenia dotyczące czynności, które może wykonywać onInstall(e); więcej informacji autoryzację. Najczęstszym zastosowaniem funkcji onInstall(e) jest wywołanie metody onOpen(e) w celu dodania niestandardowe menu. Po zainstalowaniu dodatku plik jest już otwarty, w związku z tym onOpen(e) nie uruchamia się samodzielnie, 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ść reguł onEdit(e) korzysta z informacji podanych w tabeli event, aby odpowiednio zareagować. Na przykład funkcja onEdit(e) poniżej ustawia komentarz do komórki, która rejestruje datę ostatniej modyfikacji.

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 zaznaczania w arkuszu kalkulacyjnym. Aby aktywować tę regułę, musisz odświeżyć arkusza kalkulacyjnego po dodaniu reguły i przy każdym otwarciu arkusza.

Jeśli zaznaczenie zostanie w krótkim czasie przeniesione między wieloma komórkami, niektóre elementy zaznaczone zdarzenia zmiany mogą być pomijane, aby skrócić czas oczekiwania. Na przykład, jeśli wiele elementów zmiany są wprowadzane w ciągu dwóch sekund od siebie, tylko pierwszy i ostatni zmiana wyboru spowoduje włączenie reguły onSelectionChange(e).

W przykładzie poniżej jeśli wybrana jest pusta komórka, funkcja onSelectionChange(e) ustawia jej wartość 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)

Reguła doGet(e) uruchamia się automatycznie, gdy użytkownik odwiedza aplikacja internetowa lub program wysyła żądanie HTTP GET do aplikacji internetowej. doPost(e) działa, gdy program wysyła żądanie HTTP POST do aplikacji internetowej. Te aktywatory opisujemy dokładniej w przewodnikach aplikacje internetowe, usługa HTML, i usługa treści. Pamiętaj, że doGet(e) i doPost(e) nie podlegają wymienionym wyżej ograniczeniom.

Dostępne typy reguł

jeśli ograniczenia dotyczące prostych reguł uniemożliwiają im wyzwalacza, który można zainstalować. może zamiast tego działać. W tabeli poniżej znajdziesz podsumowanie typów reguł dla każdego typu zdarzenia. na przykład Arkusze, Prezentacje, Formularze Google Wszystkie dokumenty obsługują proste aktywatory otwarte, ale tylko Arkusze, Dokumenty i Formularze obsługują tę funkcję Otwarte aktywatory z możliwością zainstalowania.

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
Samodzielne

function doPost(e)

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