Proste aktywatory

Reguły umożliwiają aplikacji 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 onOpen(e), które są uruchamiane, gdy użytkownik otwiera plik Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Instalacyjne reguły mają 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 wyzwalaną funkcję obiekt zdarzenia zawierający informacje o kontekście, w jakim wystąpiło zdarzenie.

Pierwsze kroki

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

  • onOpen(e) działa, gdy użytkownik otwiera arkusz kalkulacyjny, dokument, prezentację lub formularz, które może edytować.
  • onInstall(e) działa, gdy użytkownik zainstaluje Dodatek do Edytora z 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 otwiera aplikację internetową lub 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 powyższych nazwach funkcji jest obiektem zdarzenia przekazywanym do funkcji. Obiekt zawiera informacje o kontekście, który spowodował uruchomienie reguły. Używanie go jest opcjonalne.

Ograniczenia

Proste reguły są uruchamiane automatycznie bez pytania użytkownika o upoważnienie, dlatego podlega kilku ograniczeniom:

  • Skrypt musi być powiązany z plikiem Arkuszy, Prezentacji, Dokumentów lub Formularzy Google albo może 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).
  • Wykonanie skryptów i żądania do interfejsu API nie powodują uruchamiania aktywatorów. Na przykład wywołanie Range.setValue() w celu edycji komórki nie spowoduje uruchomienia aktywatora arkusza kalkulacyjnego onEdit.
  • Nie ma jednak dostępu do usług, które wymagają autoryzacji. Na przykład prosta reguła nie może wysłać e-maila, ponieważ usługa Gmail wymaga autoryzacji, ale prosta reguła może przetłumaczyć wyrażenie w usłudze języka, które jest anonimowe.
  • Mogą modyfikować powiązany plik, ale nie mogą uzyskać dostępu do innych plików, bo wymaga to autoryzacji.
  • To, czy zostanie ona określona, zależy od złożonego zestawu ograniczeń zabezpieczeń.
  • Nie mogą trwać dłużej niż 30 sekund.
  • W pewnych okolicznościach Dodatki do edytora uruchamiają proste reguły onOpen(e) i onEdit(e) w trybie bez autoryzacji, co wiąże się z dodatkowymi komplikacjami. Więcej informacji znajdziesz w przewodniku po cyklu życia dodatku do autoryzacji.
  • Proste aktywatory podlegają limitom aktywatora Apps Script.

Te ograniczenia nie obowiązują w usługach doGet(e) i doPost(e).

onOpen(e)

Reguła onOpen(e) jest uruchamiana automatycznie, gdy użytkownik otworzy arkusz kalkulacyjny, dokument, prezentację lub formularz, które może edytować. (reguła nie działa podczas odpowiadania na formularz, tylko po jego otwarciu) Pole onOpen(e) jest najczęściej używane do dodawania niestandardowych elementów menu do Arkuszy, Prezentacji, Dokumentów i Formularzy Google.

wyzwalacze/aktywatory.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) działa automatycznie, gdy użytkownik zainstaluje dodatek do edytora z Dokumentów, Arkuszy, Prezentacji lub Formularzy Google. Reguła nie będzie działać, gdy użytkownik zainstaluje dodatek ze strony Google Workspace Marketplace. Pamiętaj, że onInstall(e) ma pewne ograniczenia. Dowiedz się więcej o autoryzacji. Najczęstszym zastosowaniem metody onInstall(e) jest wywołanie metody onOpen(e) w celu dodania niestandardowych menu. W końcu zainstalowany dodatek jest już otwarty, więc onOpen(e) nie będzie działać samodzielnie, dopóki plik nie zostanie ponownie otwarty.

wyzwalacze/aktywatory.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) jest uruchamiana 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 odpowiedzieć prawidłowo. Na przykład funkcja onEdit(e) poniżej ustawia komentarz do komórki, która rejestruje ostatnią zmianę.

wyzwalacze/aktywatory.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) jest uruchamiana automatycznie, gdy użytkownik zmieni wybór w arkuszu kalkulacyjnym. Aby aktywować regułę, musisz ją odświeżyć po dodaniu i każdym otwarciu arkusza.

Jeśli zaznaczenie jest przenoszone między kilkoma komórkami w krótkim czasie, niektóre zdarzenia zmiany zaznaczenia mogą zostać pominięte, aby skrócić czas oczekiwania. Jeśli na przykład wiele zmian wyboru zostanie wprowadzonych w ciągu dwóch sekund od siebie, tylko pierwsza i ostatnia zmiana będą aktywować regułę onSelectionChange(e).

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

wyzwalacze/aktywatory.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) jest uruchamiany automatycznie, 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. Te wyzwalacze są bardziej przedstawione w przewodnikach po aplikacjach internetowych, usłudze HTML i usłudze treści. doGet(e) i doPost(e) nie podlegają ograniczeniom opisanym powyżej.

Dostępne typy reguł

Jeśli ograniczenia prostych reguł nie spełniają Twoich wymagań, może wystarczyć reguła do zainstalowania. W tabeli poniżej podano typy reguł, które są dostępne 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ą możliwe do zainstalowania reguły.

Zdarzenie Proste aktywatory Reguły 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
Nakierowane na czas (zegar)
Arkusze
Prezentacje
Formularze
Dokumenty
Witryny
Samodzielne
Pobierz
Witryny
Wersja samodzielna

function doGet(e)
na karcie Społeczność
Witryny
Wersja samodzielna

function doPost(e)

* Zdarzenie otwarte w Formularzach Google nie występuje, gdy użytkownik otwiera formularz, ale aby go zmodyfikować w edytorze.