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 zastrzeżonych funkcji wbudowanych w Apps Script, takich jak funkcja onOpen(e), która jest wykonywana, gdy użytkownik otworzy plik Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Instalowane aktywatory oferują więcej możliwości niż proste aktywatory, ale przed użyciem muszą zostać aktywowane. W przypadku obu typów wyzwalaczy Apps Script przekazuje funkcji wywołanej obiekt zdarzenia, który zawiera informacje o kontekście, w którym wystąpiło zdarzenie.

Pierwsze kroki

Aby użyć prostego czynnika uruchamiającego, utwórz funkcję, która używa jednej z tych zarezerwowanych nazw funkcji:

  • onOpen(e) jest wykonywane, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, do których ma uprawnienia do edycji.
  • onInstall(e) jest wykonywany, gdy użytkownik zainstaluje dodatek do edytora w Dokumentach, Arkuszach, Prezentacjach lub Formularzy Google.
  • onEdit(e) jest wykonywane, gdy użytkownik zmieni wartość w arkuszu kalkulacyjnym.
  • onSelectionChange(e) jest wykonywane, gdy użytkownik zmieni wybór w arkuszu kalkulacyjnym.
  • doGet(e) jest wykonywany, gdy użytkownik odwiedza aplikację internetową lub gdy program wysyła żądanie HTTP GET do aplikacji internetowej.
  • doPost(e) działa, gdy program wysyła żądanie HTTP POST do aplikacji internetowej.

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 jego użycie jest opcjonalne.

Ograniczenia

Ponieważ proste reguły działają automatycznie, bez pytania użytkownika o autoryzację, podlegają kilku ograniczeniom:

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

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

onOpen(e)

Reguła onOpen(e) działa automatycznie, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, do których ma uprawnienia do edycji. (wyzwalacz nie działa, gdy użytkownik odpowiada na formularz, tylko gdy otwiera go, aby go edytować). 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)

onInstall(e)uruchamia się automatycznie, gdy użytkownik zainstaluje dodatek do edytora w Dokumentach, Arkuszach, Prezentacjach lub Formularze Google. Reguła nie zostanie uruchomiona, gdy użytkownik zainstaluje dodatek na stronie Google Workspace Marketplace. Pamiętaj, że onInstall(e) ma pewne ograniczenia. Dowiedz się więcej o autoryzacji. Najczęstszym zastosowaniem funkcji onInstall(e) jest wywołanie funkcji onOpen(e) w celu dodania menu niestandardowych. W końcu po zainstalowaniu dodatku plik jest już otwarty, a 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)

Wyzwalacz onEdit(e) działa automatycznie, gdy użytkownik zmieni wartość dowolnej komórki w arkuszu kalkulacyjnym. Większość onEdit(e) używa informacji z obiektu zdarzenia, aby odpowiednio zareagować. Na przykład funkcja onEdit(e) poniżej ustawia komentarz w komórce, który zapisuje ostatni czas jej 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)

onSelectionChange(e)uruchamia się automatycznie, gdy użytkownik zmieni zaznaczenie w arkuszu kalkulacyjnym. Aby aktywować tę regułę, musisz odświeżyć arkusz kalkulacyjny po dodaniu reguły i za każdym razem, gdy go otworzysz.

Jeśli zaznaczenie przemieszcza się między wieloma komórkami w krótkim czasie, niektóre zdarzenia zmiany zaznaczenia mogą zostać pominięte, aby skrócić czas oczekiwania. Jeśli np. w ciągu 2 sekund nastąpi wiele zmian w wybranych elementach, reguła onSelectionChange(e) zostanie uruchomiona tylko w przypadku pierwszego i ostatniego wyboru.

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

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)

Wyzwalacz doGet(e) działa automatycznie, gdy użytkownik odwiedza aplikację internetową lub program wysyła żądanie HTTP GET do aplikacji internetowej. Wyzwalacz doPost(e) działa, gdy program wysyła żądanie HTTP POST do aplikacji internetowej. Te wyzwalacze są opisane szczegółowo w przewodnikach dotyczących aplikacji internetowych, usługi HTML i usługi treści. Pamiętaj, że doGet(e) i doPost(e) nie podlegają wyżej wymienionym ograniczeniom.

Dostępne typy reguł

Jeśli ograniczenia prostego reguł uniemożliwiają ich dostosowanie do Twoich potrzeb, możesz użyć instalowalnego reguły. W tabeli poniżej znajdziesz podsumowanie typów reguł dostępnych w przypadku poszczególnych typów zdarzeń. Na przykład Arkusze, Prezentacje, Formularze i Dokumenty Google obsługują proste reguły uruchamiane po otwarciu, ale tylko Arkusze, Dokumenty i Formularze obsługują instalowane reguły uruchamiane po otwarciu.

Zdarzenie Proste reguły 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
Czasowy (zegar)
Sheets
Slides
Forms
Docs
Standalone
Pobierz
Samodzielny

function doGet(e)
Opublikuj
Samodzielny

function doPost(e)

* Zdarzenie otwarcia formularza Google nie występuje, gdy użytkownik otwiera formularz, aby na niego odpowiedzieć, ale gdy edytor otwiera formularz, aby go zmodyfikować.